Address Migration Documentation

Convert current address to new format

Updating the convert address API is a crucial step for developers who need to migrate addresses between the old and new standardized formats used by VIETMAP. This API allows users to input either an old or new address format and receive a structured response with the corresponding converted address, along with additional details such as boundaries and display names.

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 provided by VIETMAP for customer's account
focus	number	no	Specify the center of the search context expressed as coordinates. Required if migrate_type = 2	10.758867,106.675566.
text	string	yes	Address input (old or new format)	197 tran phu p4 q5
migrate_type	number	no	Migration type: 1: migrate from old to new format 2: migrate from new to old format. If migrate_type = 2, focus param must be provided	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	Array containing boundary information (ward, district, city)

For the boundaries array:

Sub-Parameter	Type	Description
type	int	Type of boundary (0 for city, 1 for district, 2 for ward)
id	int	Unique identifier for the boundary
name	string	Name of the boundary
prefix	string	Prefix of the boundary (e.g., "Phường" for ward)
full_name	string	Full name of the boundary (e.g., "Phường 9" for ward)