Skip to content

Reverse - v4

Reverse

Reverse v4 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.

Playground

You can test the Reverse v4 API in our Live Map or Playground.

AI Agent Integration ✨ NEW

Download the optimized doc for AI agent integration (Search + Reverse): Search & Geocoding Agent Doc

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/v3 to /api/reverse/v4; add display_type to control output (1=new, 2=old, 4=two-items list, ⅚=hybrid in-object).
  • Request still uses lat and lng; behavior is compatible. v4 introduces merged 2-level admin model in responses.
  • v4 responses can include data_old/data_new to carry the alternate format.
  • For v3-compatible payloads, call v4 with display_type=2; for side-by-side comparison or hybrid in one item, use display_type=4, 5, or 6.

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&6
Response

[
    {
        "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
facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo