Skip to content

Autocomplete - v4

autocomplete

Updating Autocomplete API is a valuable resources that allows developers to integrate autocomplete functionality into their applications. This API is designed to help users quickly find and select items from a large set of options by suggesting potential matches as they type.

URL

https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text={text}&focus={lat,long}&display_type={display_type}

Method

GET

Migrate from v3 → v4 (short)

  • Endpoint changes from /api/autocomplete/v3 to /api/autocomplete/v4; add display_type to control output (1=new, 2=old, 3=auto, ⅚=both).
  • Responses can use a new 2-level admin model (ward → province); v4 may include data_old/data_new to carry the alternate format if you choose display_type=5 or 6.
  • For v3-compatible payloads, call v4 with display_type=2.
  • V4 api uses different ref_id, please refer to Place v4 API for more detail, which replaces the old Place API.
  • We suggest to use display_type=5 for better migration experience.

See the previous version docs: Autocomplete v3.

Parameters

Parameter Type Required Description Example
apikey string yes API provided by VIETMAP for customer's account
focus string no Specify the center of the search context expressed as coordinates (lat,lng). 10.758867,106.675566
text string yes User desired input Cong ty
display_type number no Result display type. Follow Display Type Options for more detail 1
cityId number no Every city has a unique ID, which is used to filter search results 12
distId number no Every district has a unique ID, which is used to filter search results 1292
wardId number no Every ward has a unique ID, which is used to filter search results 984332
circle_center string no The central coordinate (lat,lng) position of the area to be searched 10.758867,106.6755666
circle_radius number no The radius of the search area (in meters) 200
cats string no Provide full list of POI categories. Click here POI Categories 1002-1
layers string no Represent for certain type of data such as POI,ADDRESS,VILLAGE,WARD,DIST,CITY,STREET POI
admin_new boolean no Flag to indicate use of new or old administrative boundaries. Only work with filter by admin id (city, district, ward). Example, if it receive false, while filter HoChiMinh City by Id, it only response data in old geometries, does not include BinhDuong and VungTau false
#### Display type options
Value Label Description
1 Response New Format New merged administrative format (2 levels: ward, city).
2 Response Old Format Old administrative format (3 levels: ward, district, city).
3 Response as Input Format API will detect user input and response model like input format.
5 Response both New & Old Returns new-format object and indicates old (legacy) boundaries.
6 Response both Old & New Returns old-format object and indicates updated (new) boundaries.

Example

Input 

https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text=197 tran phu&focus=10.75887508,106.67538868&display_type=6
Response

If you need detailed information about the place, please use the Vietmap Place API

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
        "distance": 0.06911172534949989,
        "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"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
            "distance": 0.06911172534949989,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú 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"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_new": null,
            "data_old": null
        },
        "data_old": null
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
        "distance": 0.06911172534949989,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 Trần Phú 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"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": null,
        "data_old": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
            "distance": 0.06911172534949989,
            "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"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_new": null,
            "data_old": null
        }
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
        "distance": 0.05455783214665687,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú 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"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFaYhBYVA",
        "distance": 0.05455783214665687,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường 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"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
        "distance": 0.05455783214665687,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú 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"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

Response description

Autocomplete API will respond to a list that contains up to 10 places.

Parameter Type Description
ref_id string Reference ID for the Point of Interest (POI). May include a prefix reflecting display type. Use Vietmap Place API to get detail info.
distance number Distance value, in kilometer
address string Full address including street, ward, district, and city.
name string Name of the Point of Interest (POI)
display string Display name containing detailed information of the POI address
boundaries array Array containing boundary information (ward, district, city).
categories array Array containing categories associated with the POI
entry_points array Array containing entry points for the POI. This value will available for some special address, like airport, hotel,...
data_old object or null Old-format variant of this result (when applicable to the chosen display type), otherwise null.
data_new object or null New-format variant of this result (when applicable to the chosen display type), otherwise null.

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)

For the entry_points array:

Sub-Parameter Type Description
ref_id string Reference ID for the Point of Interest (POI)
name string Name of the Point of Interest (POI)

For the data_old and data_new objects:

Sub-Parameter Type Description
ref_id string Reference ID for the result variant
distance number Distance value, in kilometer
address string Full address
name string POI name
display string Display text containing detailed address info
boundaries array Same schema as the boundaries array above
categories array POI category codes
entry_points array Entry points for the POI (if available)

If you need detailed information about the entrypoint, please use the Vietmap Place v4 API

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo