Skip to content

Autocomplete - v4

Autocomplete API v4

autocomplete

Autocomplete v4 returns up to 10 place suggestions for the text the user is typing, matching both pre- and post-merger address formats. Call it on each input change (debounced), show display to the user, and when they pick a row pass its ref_id to Place v4 for coordinates and full address details. Pass focus (the user's location) to rank nearby results first.

Playground

Try it in the Playground

Call Autocomplete v4 with real data, no code required: Open Playground · or explore it on the Live Map

AI Agent Integration ✨ NEW

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

Or try it in Postman.

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

  • Endpoint changes from /api/autocomplete/v3 to /api/autocomplete/v4; add display_type to control output (1=new, 2=old, 3=auto, ⅚=both).
  • v4 returns the new 2-level admin model (ward → province) for display_type=1, 5, and 3 when the input is a new-format address: boundaries then has no type=1 (district) entry. With display_type=5/6 each result also carries the other format in data_old/data_new; for other values both are null.
  • For v3-compatible payloads, call v4 with display_type=2.
  • v4 ref_id values are not compatible with the old Place API — look them up with Place v4.
  • For migration, use display_type=5: the new format is the main object and the old 3-level format is in data_old, so existing parsing keeps working while you switch.

See the previous version docs: Autocomplete v3.

Parameters

Parameter Type Required Description Example
apikey string yes API key provided by VIETMAP for your account. Register here
focus string no User's current location as lat,lng (latitude first). Biases ranking toward nearby results; if omitted, results are ranked by text match only. 10.758867,106.675566
text string yes Text the user has typed so far. Send at least 2 characters. Cong ty
display_type number no Result display type. Follow Display Type Options for more detail 1
cityId number no Filter results to one province/city. Look the ID up in the administrative address dataset 12
distId number no Filter results to one district. Look the ID up in the administrative address dataset 1292
wardId number no Filter results to one ward. Look the ID up in the administrative address dataset 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 POI category codes to filter by. See the POI Categories list. 1002-1
layers string no Restrict result types. Allowed values: POI, ADDRESS, VILLAGE, WARD, DIST, CITY, STREET. Omit to search all types. POI
admin_new boolean no true = new administrative boundaries, false = old. Only applies together with cityId/distId/wardId. Example: cityId=12&admin_new=false returns only results inside the old Ho Chi Minh City boundary (no Binh Duong, no Vung Tau). 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 Detects whether text is in the old or new format and returns results in that same format.
5 Response both New & Old Main object in the new 2-level format; the old 3-level version of the same result in data_old.
6 Response both Old & New Main object in the old 3-level format; the new 2-level version of the same result in data_new.

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

[
    {
        "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

The API returns a JSON array of up to 10 places.

Parameter Type Description
ref_id string Opaque place ID, always prefixed (auto: or geocode:, depending on display type). Pass it verbatim — prefix included — as refid to Place v4 for coordinates and address details.
distance number Distance value, in kilometer
address string Administrative part of the address: ward, district (old format only), province. House number and street are in name; use display for the full string.
name string POI name, or house number + street for address results (e.g. 197 Trần Phú)
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).
categories array Array containing categories associated with the POI
entry_points array Entrances of the POI; empty array if none. Present mainly for airports, hotels and malls.
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 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

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)

Results do not include coordinates. To get lat/lng and address components for a result or an entry point, pass its ref_id to Place v4.

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