Address Migration Documentation

Convert old addresses to the new format

After Vietnam merged its provinces and wards, every address already stored in your system is an old address. This API converts them to the new administrative format, and back again when you need it.

The response comes pre-split: house number and street in name, each administrative level with its id in boundaries — write it straight into database columns, no string parsing.

What you use it for

Task	How
Migrate a whole address database	Loop over each record with migrate_type=1 and store display plus the boundaries array
Reconcile with a partner still on old addresses	Convert the other way with migrate_type=2
Clean up hand-typed addresses	Free-text addresses are rarely well formed; the API returns a normalised, split version
Sync administrative codes	Use the id inside boundaries as the key instead of matching ward/province names as text

Bulk conversion

The API handles one address per call. To migrate a whole database, loop and respect the rate limit of your plan - see Usage Limits.

Try it in the Playground

Call the Address Migration API with real data, no code required: Open Playground

AI Agent Integration NEW

Download the optimized doc for AI agent integration: Data Tools Agent Doc

Or try it in Postman.

URL

https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text={text}&focus={lat,long}

Method

GET

Parameters

Parameter	Type	Required	Description	Example
apikey	string	yes	API key provided by VIETMAP for your account. Register here
focus	number	no	A coordinate near the address, as lat,lng, used to disambiguate identical street names. Required when migrate_type=2	10.758867,106.675566
text	string	yes	Free-text address to convert. Accepts both the old and the new format	197 tran phu p4 q5
migrate_type	number	no	Conversion direction. 1: old to new (what you use to migrate data). 2: new to old, requires focus	1

Example

Input

https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text=197 tran phu p4 q5&focus=10.75887508,106.67538868

Response (migrate_type=1, old → new)

{
    "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "name": "197 tran phu ",
    "display": "197 tran phu Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "boundaries": [
        {
            "type": 2,
            "id": 18700,
            "name": "Chợ Quán",
            "prefix": "Phường",
            "full_name": "Phường Chợ Quán"
        },
        {
            "type": 0,
            "id": 12,
            "name": "Hồ Chí Minh",
            "prefix": "Thành Phố",
            "full_name": "Thành Phố Hồ Chí Minh"
        }
    ]
}

Input

https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text=197 tran phu phuong cho quan tp ho chi minh&focus=10.75887508,106.67538868&migrate_type=2

Response (migrate_type=2, new → old)

{
    "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "name": "197 Trần Phú",
    "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "boundaries": [
        {
            "type": 2,
            "id": 656652,
            "name": "4",
            "prefix": "Phường",
            "full_name": "Phường 4"
        },
        {
            "type": 1,
            "id": 1292,
            "name": "5",
            "prefix": "Quận",
            "full_name": "Quận 5"
        },
        {
            "type": 0,
            "id": 12,
            "name": "Hồ Chí Minh",
            "prefix": "Thành Phố",
            "full_name": "Thành Phố Hồ Chí Minh"
        }
    ]
}

Response description

Parameter	Type	Description
address	string	Administrative part of the address: ward and city in the new format; ward, district and city in the old format. The street is in name.
name	string	House number and street, as parsed from text.
display	string	name and address joined into one string — store this as the full address.
boundaries	array	Administrative units of the address, from the smallest level up (ward, district, province)

For the boundaries array:

Sub-Parameter	Type	Description
type	int	Administrative level (0 = province/city, 1 = district, 2 = ward)
id	int	Unique identifier of the administrative unit
name	string	Name of the administrative unit, without its prefix
prefix	string	Administrative level prefix. Example: Phường, Quận, Thành Phố
full_name	string	Full name including the prefix. Example: Phường 9