(opens in a new tab)gmap cloud
Talk to usContact
AddressesBasic2 min readIncludes code

Vietnamese addresses after the merger: matching old and new addresses with an API

The 2025 administrative reorganisation changed the province, district and commune parts of a great many addresses. This guide uses coordinates as an anchor to match old and new addresses in your data.

· GMap Cloud

What changed

Since 1 July 2025, local government has operated a two-level model: 34 provinces and centrally governed cities, and the commune level (communes, wards and special zones). The district level was removed and many provinces and communes were merged.

Former modelNew model
Provinces and cities6334
Administrative levels in an address3 (province – district – commune)2 (province – commune)
Names in the GMap APIGADM63, addr63, poi63GADM34, addr34, poi34

Why not rename from a lookup table

A former commune can be split across several new units, and the same street name appears in many places. Replacing names from a table easily assigns the wrong unit. A safer approach is to locate the address first, then look up the administrative units at that location under each model.

Match by coordinate

  1. Find the address coordinate with the search API (or use a stored coordinate).
  2. Call reverse geocoding at that coordinate with subtype=addr34 and subtype=addr63.
  3. Store both address labels with the coordinate; flag records with only one form for review.
Example: 114 Nguyen Hue, Ho Chi Minh City
# 34-province address (two levels)
curl 'https://cloud.gmap.vn/api/idunn/v1/reverse/10.7769:106.7009?lang=vi&subtype=addr34' \
  --header 'x-api-key: public-gmap-cloud-x-api-key-demo'

# 63-province address (three levels)
curl 'https://cloud.gmap.vn/api/idunn/v1/reverse/10.7769:106.7009?lang=vi&subtype=addr63' \
  --header 'x-api-key: public-gmap-cloud-x-api-key-demo'
ModelReturned address (public demo, 11 October 2026)
63 provinces114 Đường Nguyễn Huệ, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh
34 provinces114 Đường Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh

When updating your data

  • Keep the old address rather than overwriting it: records, invoices and contracts before 1 July 2025 still use it.
  • Store the coordinate with the address so later updates need no new search.
  • Reverse geocoding returns the nearest address at the coordinate; for large sites, check the distance in the response.
  • The demo key is rate-limited; bulk updates need a key issued for your application.