Address Migration Playground

    Convert addresses old ↔ new

    Vietnam merged its provinces and wards, so a place can be written the old way or the new way. This API converts both directions and returns the matching administrative units with their IDs.

    Code samples

    Example with sample parameters — fill in the form to get code for your own request.

    curl 'https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1'

    Replace YOUR_API_KEY with your API key before running.

    // In production, read the key from an environment variable instead.
const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams([
  ["apikey", API_KEY],
  ["text", "197 tran phu p4 q5"],
  ["focus", "10.75887508,106.67538868"],
  ["migrate_type", "1"],
]);

const response = await fetch(`https://maps.vietmap.vn/api/migrate-address/v3?${params}`);
if (!response.ok) {
  throw new Error(`Vietmap ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data);

    Replace YOUR_API_KEY with your API key before running.

    import requests

# In production, read the key from an environment variable instead.
API_KEY = "YOUR_API_KEY"

params = [
    ("apikey", API_KEY),
    ("text", "197 tran phu p4 q5"),
    ("focus", "10.75887508,106.67538868"),
    ("migrate_type", "1"),
]

response = requests.get("https://maps.vietmap.vn/api/migrate-address/v3", params=params, timeout=30)
response.raise_for_status()
print(response.json())

    Replace YOUR_API_KEY with your API key before running.

    https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1

    Replace YOUR_API_KEY with your API key before running.

    I need to integrate Vietmap's Address Migration API v3 into my application.

Official documentation: https://maps.vietmap.vn/docs/migrate-address/migrate-address-docs/

Here is a sample request that works in the Vietmap API Playground:

GET https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1

Parameters in use:
- text = 197 tran phu p4 q5
- focus = 10.75887508,106.67538868
- migrate_type = 1

Write code in [my language / framework] that calls this API, with these requirements:
1. Read the API key from the VIETMAP_API_KEY environment variable; never hard-code it.
2. Send the parameters in the query string exactly as in the sample; repeated parameters (such as `point`) must keep their order.
3. Handle Vietmap's HTTP errors:
   - 401: the API key is wrong or revoked.
   - 403: the key is restricted to a domain / IP that does not match.
   - 423: the API is not enabled for the key's consumer, OR the account is out of credit — tell them apart by the response body ("exceeded credit" means out of credit).
   - 429: rate limit exceeded — retry with increasing backoff.
4. Set a request timeout, and define types (type / interface / dataclass) for the response.

If unsure about a field name, look it up in the documentation linked above instead of guessing.

    Paste into ChatGPT, Claude… to generate integration code. The prompt never contains your API key.

    Open in ChatGPTOpen in Claude
    https://tools.vietmap.vn/playground/en/migrate-address?text=197+tran+phu+p4+q5&focus=10.75887508,106.67538868&migrate_type=1

    Opens the playground with exactly these parameters — for the docs or a colleague. The link never contains an API key.

    What is the Address Conversion API?

    The Address Migration API, an address conversion API, converts an address between the old and new formats after the administrative reorganisation (merged provinces, no district level, merged wards). Old → new needs only the address; new → old also needs an approximate coordinate (focus), because several former wards now share one name. The result lists the matching administrative units with their ids and names.

    What it is for

    • Updating customer addresses in a database to the new units.
    • Reconciling records and contracts still on old addresses.
    • Showing old and new addresses side by side.
    • Cleaning data before batch geocoding.

    Sample request

    GET https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197%20tran%20phu%20p4%20q5&migrate_type=1

    migrate_type=1: old → new · migrate_type=2: new → old (focus required).

    Address Conversion API FAQ

    What is an address conversion API?
    It converts addresses between Vietnam’s former and new administrative units after the 2025 reorganisation (merged provinces, no district level, merged wards and communes). For example, “197 Tran Phu, Ward 4, District 5” becomes a new address in Cho Quan Ward, Ho Chi Minh City.
    Can a new address be converted back to the old one?
    Yes, with migrate_type=2. That direction also needs an approximate coordinate (focus), because several former wards merged into one, so the address alone cannot tell which old one it was.
    What does the result contain?
    The converted address and the matching administrative units level by level (province or city, ward or commune, plus district for a former address), each with its id, name and full name. The ids work as province and ward filters in the Geocoding and Autocomplete APIs, or as keys in your own database.
    Does it cost anything to try the Address Conversion API?
    The playground comes with a demo API key, so you can call the Address Conversion API straight from the browser without signing up. To build it into a product, register a VIETMAP account for your own key. Usage is billed per transaction, each API converting requests to transactions at its own rate; the pricing page has the details and the free trial.