# Geocode - v4 Source: https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-v4/ ## Geocode version for merged location search ![geocode](https://maps.vietmap.vn/docs/assets/geocode.webp) Geocode v4 takes a full address string (e.g. `197 Trần Phú, phường 4, quận 5, TP.HCM`) and returns up to 10 matching places, each with a `ref_id`, a normalized address and its administrative units. The response has no coordinates — pass the `ref_id` to [Place v4](https://maps.vietmap.vn/docs/map-api/place-v4/) to get `lat`/`lng`. !!! warning "Important" Geocode v4 expects a full address string; partial input may return an empty array. For search-as-you-type, use [Autocomplete v4](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/). ### Playground !!! tip "Try it in the Playground" Call Geocode v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/geocode)** !!! tip "AI Agent Integration :sparkles: NEW" Download the optimized doc for AI agent integration (Geocode + Reverse): **Geocode & Reverse Geocoding Agent Doc** · 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/search/v4?apikey={your-apikey}&text={text}&focus={lat,long}&display_type={display_type} ``` ### Method GET ### Migrate from v3 → v4 - Endpoint changes from `/api/search/v3` to `/api/search/v4`; add `display_type` to control output (1=new, 2=old, 3=auto, 5 or 6=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](https://maps.vietmap.vn/docs/map-api/place-v4/) 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: [Geocode v3](https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-ver3.0/). ### Parameter |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)|| |text|string|yes|Full address string to geocode, e.g. `197 Trần Phú, phường 4, quận 5, TP.HCM`. Not for partial input — see the warning above|197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh| |focus|string|no|GPS cordinates|10.759540242000032, 106.67660114000005| |display_type|number|no|Result display type. Follow [Display Type Options](#display-type-options) for more detail|1| |layers|string|no|Represent for certain type of data such as `POI`,`ADDRESS`,`VILLAGE`,`WARD`,`DIST`,`CITY`,`STREET`|POI| |circle_center|number|no|The central coordinate(lat/lng) position of the area to be searched |10.758867051669924,106.6755666901197| |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](https://vietmapcorp-my.sharepoint.com/:x:/g/personal/sennd_vietmap_vn/EacvkT3kgtBHmYUPnI5Nuj8BKHfvM6_HFNS_THOuxDty8A?e=5M8IAM&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiIyNy8yMzAyMDUwMTQyMSIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D){:target="_blank}|1002-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| |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** ```url https://maps.vietmap.vn/api/search/v4?apikey={your-apikey}&focus=10.75887508,106.67538868&display_type=6&text=197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh ``` [:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/geocode?text=197%20Tr%E1%BA%A7n%20Ph%C3%BA,%20ph%C6%B0%E1%BB%9Dng%204,%20qu%E1%BA%ADn%205,%20th%C3%A0nh%20ph%E1%BB%91%20H%E1%BB%93%20Ch%C3%AD%20Minh&focus=10.75887508,106.67538868&display_type=6){ .md-button .md-button--primary } **Response** If you need detailed information about the place, please use the [Vietmap Place API](https://maps.vietmap.vn/docs/map-api/place-v4/) === "Response both Old & New
`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
`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
`display_type=3`" ```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": null, "data_old": null } ] ``` === "Response Old Format
`display_type=2`" ```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": null, "data_old": null } ] ``` === "Response New Format
`display_type=1`" ```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": null } ] ``` ### Response description Geocode 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](https://maps.vietmap.vn/docs/map-api/place-v4/) 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 | Administrative units of the address, from the smallest level up. In the new display format each entry is a ward or a province.| | categories | array | Array containing categories associated with the POI (see POI category codes in the parameter section: “cats”). | | entry_points| array | Array containing entry points associated with 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 | integer| Administrative level (`0` = province/city, `1` = district, `2` = ward) | | id | integer| 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) | If you need detailed information about the entrypoint, please use the [Vietmap Place v4 API](https://maps.vietmap.vn/docs/map-api/place-v4/) ### 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 Geocode v4 on the Playground](https://tools.vietmap.vn/playground/geocode)**