Reverse - v4
Reverse Demo API is a demonstration version of the reverse geocoding service that allows developers to test and explore location search features. This API provides a way to convert geographic coordinates (latitude and longitude) into readable addresses and location information, helping developers understand the capabilities before implementing the full version.
URL¶
https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat={latitude}&lng={longitude}&display_type={display_type}
Method¶
GET
Migrate from v3 → v4 (short)¶
- Endpoint changes from
/api/reverse/v3to/api/reverse/v4; adddisplay_typeto control output (1=new, 2=old, 4=two-items list, ⅚=hybrid in-object). - Request still uses
latandlng; behavior is compatible. v4 introduces merged 2-level admin model in responses. - v4 responses can include
data_old/data_newto carry the alternate format. - For v3-compatible payloads, call v4 with
display_type=2; for side-by-side comparison or hybrid in one item, usedisplay_type=4,5, or6.
See the previous version docs: Reverse v3.
Parameters¶
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| apikey | string | yes | API key provided by VIETMAP for customer's account | |
| lat | number | yes | Latitude of desired place | 10.759221 |
| lng | number | yes | Longitude of desired place | 106.675901 |
| display_type | number | no | Result display type. Follow Display Type Options for more detail | 1 |
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). |
| 4 | Response two objects | Returns both formats as two items in the list (a new-format item and an old-format item). |
| 5 | Response both New & Old | Returns new-format object at top level and provides old-format variant in data_old. |
| 6 | Response both Old & New | Returns old-format object at top level and provides new-format variant in data_new. |
Example¶
Input
https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat=10.759221&lng=106.675901&display_type=1
[
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80930474606",
"distance": 2.5788156956946213E-06,
"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_old": null,
"data_new": {
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80922545F1007",
"distance": 2.5788156956946213E-06,
"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_old": null,
"data_new": null
}
}
]
[
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E7E570E4101",
"distance": 0,
"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_old": {
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
"distance": 0,
"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_old": null,
"data_new": null
},
"data_new": null
}
]
[
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E7E570E4101",
"distance": 0,
"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_old": null,
"data_new": null
},
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
"distance": 0,
"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_old": null,
"data_new": null
}
]
[
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
"distance": 0,
"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_old": null,
"data_new": null
}
]
[
{
"lat": 10.759221,
"lng": 106.675901,
"ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80922545F1007",
"distance": 2.5788156956946213E-06,
"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_old": null,
"data_new": null
}
]
Response description¶
Reverse Demo API will respond with a list that contains location information for the given coordinates.
| Parameter | Type | Description |
|---|---|---|
| lat | double | Latitude coordinate of the location |
| lng | double | Longitude coordinate of the location |
| ref_id | string | Reference ID for the location |
| distance | double | Distance of the location from the queried point, value in kilometer |
| address | string | Full address including ward, district, and city |
| name | string | Name of the specific location or street address |
| display | string | Display name containing complete address information |
| boundaries | array | Array containing boundary information (ward, district, city) |
| categories | array | Array containing categories associated with the location |
| entry_points | array | Array containing entry point information for the location |
| data_old | object or null | Location object in the old admin format (3 levels). Available for hybrid display types (e.g., 5), otherwise null. |
| data_new | object or null | Location object in the new merged admin format (2 levels). Available for hybrid display types (e.g., 6), 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 Chợ Quán" 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) |
If you need detailed information about the entry point, please use the Vietmap Place API
For the data_old and data_new objects:
| Sub-Parameter | Type | Description |
|---|---|---|
| lat | double | Latitude coordinate of the location |
| lng | double | Longitude coordinate of the location |
| ref_id | string | Reference ID for the location |
| distance | double | Distance of the location from the queried point, in kilometer |
| address | string | Full address |
| name | string | Name of the specific location or street address |
| display | string | Display name containing complete address information |
| boundaries | array | Same schema as the boundaries array above |
| categories | array | Categories associated with the location |
| entry_points | array | Same schema as the entry_points array above |
