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.

Playground

You can test the Autocomplete v4 API in our Live Map or Playground.

AI Agent Integration ✨ NEW

Download the optimized doc for AI agent integration: Search & Geocoding Agent Doc

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

Best Practices

1. Always pass focus — user's current location

focus is the single most impactful parameter for result quality. It biases ranking toward places near the user, so a search for "Cà phê" in Ho Chi Minh City won't return results from Hanoi.

  • Mobile apps: pass the device's latest GPS coordinate.
  • Web apps: pass the map's current center, or use the browser Geolocation API.
  • Fallback: if location is unavailable, use the center of the city you expect the user to be in.
focus=10.776655,106.700876   ← user's current lat,lng

Without focus, results are ranked by text relevance only — two places with identical names in different cities will have arbitrary ordering.

2. Send text on every keystroke (debounced)

Call the API on each input change, debounced at 200–300 ms. Shorter delays waste transactions; longer delays make the UI feel sluggish.

  • Minimum query length: 2 characters — single characters produce low-quality, high-volume results.
  • Cancel the previous in-flight request before sending a new one (use AbortController on web, cancel tokens on mobile).

3. Use display_type=5 (recommended default)

Returns new 2-level format as the primary result and old 3-level format in data_old. Covers both address formats in one response without a second call.

4. Call Place v4 only on selection — not on every suggestion

Each Place v4 call counts as a transaction. Call it once, after the user taps/clicks a specific result to get detailed information. Do not call it for every item in the suggestion list.

5. Show display to the user — use ref_id internally

display is the human-readable label (e.g. "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh"). ref_id is an opaque token — pass it verbatim to Place v4.

6. More Secure

If possible, please encode the ref_id on the server side, and when user selects a suggestion, send the encoded ref_id to your server, decode it there and call Place API with the decoded ref_id. This way, you can keep your API secure from any potential abuse.

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