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 important part: the API returns the address already split into parts, with administrative boundary ids, so you can write it straight into database columns instead of parsing strings yourself.

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 here: Convert Address tool

AI Agent Integration NEW

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

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

Response example for migrate_type=1 (old to 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 example for migrate_type=2 (new to 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	Full address including street, ward, and city.
name	string	Name of the POI/Address
display	string	Display name containing detailed information of the POI 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