# Autocomplete - v4

Source: https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/

## Autocomplete API v4

 [![autocomplete]][autocomplete]
 [autocomplete]: https://maps.vietmap.vn/docs/assets/autocomplete.webp

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](https://maps.vietmap.vn/docs/map-api/place-v4/) for coordinates and full address details. Pass `focus` (the user's location) to rank nearby results first.

### Playground
!!! tip "Try it in the Playground"
    Call Autocomplete v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/autocomplete)** · or explore it on the [Live Map](https://tools.vietmap.vn/live/)

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration: **<a href="/docs/assets/agents/search-geocoding.txt" download="search-geocoding.txt">Search & Geocoding Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

Or try it in [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### URL
```swift
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, 5/6=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](https://maps.vietmap.vn/docs/map-api/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](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-ver3.0/).

### Parameters

|Parameter|Type|Required|Description|Example|
|--- |--- |--- |--- |--- |
|apikey|string|yes|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)||
|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](#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](https://github.com/vietmap-company/vietnam_administrative_address)|12|
|distId|number|no|Filter results to one district. Look the ID up in [the administrative address dataset](https://github.com/vietmap-company/vietnam_administrative_address)|1292|
|wardId|number|no|Filter results to one ward. Look the ID up in [the administrative address dataset](https://github.com/vietmap-company/vietnam_administrative_address)|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](https://vietmapcorp-my.sharepoint.com/:x:/g/personal/sennd_vietmap_vn/EacvkT3kgtBHmYUPnI5Nuj8BKHfvM6_HFNS_THOuxDty8A?e=5M8IAM&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiIyNy8yMzAyMDUwMTQyMSIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D){:target="_blank} 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**
```url
https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text=197 tran phu&focus=10.75887508,106.67538868&display_type=6
```

[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/autocomplete?text=197%20tran%20phu&focus=10.75887508,106.67538868&display_type=6){ .md-button .md-button--primary }

**Response**

=== "Response both Old & New<br>`display_type=6`"
    ```json
    [
        {
            "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
        }
    ]
    ```
=== "Response both New & Old<br>`display_type=5`"
    ```json
    [
        {
            "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
            }
        }
    ]
    ```
=== "Response as Input Format<br>`display_type=3`"
    ```json
    [
        {
            "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 Old Format<br>`display_type=2`"
    ```json
    [
        {
            "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": []
        }
    ]
    ```
=== "Response New Format<br>`display_type=1`"

    ```json
    [
        {
            "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](https://maps.vietmap.vn/docs/map-api/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](https://maps.vietmap.vn/docs/map-api/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.

### Error codes

| HTTP | Meaning | Response body |
| --- | --- | --- |
| `200` | Success | JSON as in the example above |
| `401` | Wrong or unknown API key | Empty |
| `423` | Quota used up, or this API is not enabled for the key | Plain text, e.g. `Your request is limited` |

On `423`, check the remaining quota in [Monitor API key usage](https://maps.vietmap.vn/docs/map-api/console/monitor-api-key-usage/) and whether the API is enabled for the key in [Manage API keys](https://maps.vietmap.vn/docs/map-api/console/manage-api-key/).

!!! tip "Try it with your own data"
    Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Autocomplete v4 on the Playground](https://tools.vietmap.vn/playground/autocomplete)**