Search - v4
Geocode version for merged location search¶
Updating Geocode API is a powerful tool for developers to integrate location search functionality into their applications with optimized performance. Additionally, this latest version utilizes intelligent search algorithms and methods to provide accurate and speedy search results for users.
URL¶
https://maps.vietmap.vn/api/search/v4?apikey={your-apikey}&text={text}&focus={lat,long}&display_type={display_type}
Method¶
GET
Parameter¶
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| apikey | string | yes | API provided by VIETMAP for customer's account. | |
| text | string | yes | User desired input | Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt |
| focus | string | no | GPS cordinates | 10.759540242000032, 106.67660114000005 |
| display_type | number | no | Result display type. Follow 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 | 1002-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 |
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/search/v4?apikey={your-apikey}&focus=10.75887508,106.67538868&display_type=1&text=197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh
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": "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": "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": "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 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). For the new display format, the boundaries will be returned as an array of objects, each containing ward and city. |
| 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 | Type of boundary (0 for city, 1 for district, 2 for ward) |
| id | integer | 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
