Skip to content

Reverse - v4

Reverse

Reverse v4 converts a coordinate (lat, lng) into the nearest address and its administrative boundaries. The response can use the old 3-level format (ward, district, city), the new 2-level format (ward, city), or both — choose with display_type.

Playground

Try it in the Playground

Call Reverse v4 with real data, no code required: Open Playground · or explore it on the Live Map

AI Agent Integration ✨ NEW

Download the optimized doc for AI agent integration (Search + Reverse): Search & Geocoding Agent Doc · Machine-readable schema: OpenAPI 3.1

Or try it in Postman.

URL

https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat={latitude}&lng={longitude}&display_type={display_type}

Method

GET

Migrating from v3

  • Change the path from /api/reverse/v3 to /api/reverse/v4. lat and lng are unchanged.
  • To keep v3-compatible responses, pass display_type=2. Omitting it (or display_type=1) returns the new 2-level format.
  • To get both formats in one response, pass display_type=4, 5, or 6. See Display type options.
  • Every response object now has data_old and data_new. They are null unless display_type is 5 or 6.

Previous version: Reverse v3.

Parameters

Parameter Type Required Description Example
apikey string yes API key provided by VIETMAP for your account. Register here
lat number yes Latitude of the point to look up 10.759221
lng number yes Longitude of the point to look up 106.675901
display_type number no Response format. See Display type options. 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 Both, as two items Returns both formats as two items in the list (a new-format item and an old-format item).
5 New, with data_old Returns new-format object at top level and provides old-format variant in data_old.
6 Old, with data_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=6

Run this example on the Playground

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

The response is a JSON array of location objects for the given coordinate.

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 from the query point, in kilometers
address string Administrative part of the address: ward and city in the new format; ward, district and city in the old format. The street is in name.
name string Name of the specific location or street address
display string name and address joined into one string.
boundaries array Administrative units, smallest first, ordered by type. See below.
categories array Categories of the location.
entry_points array Entry points of the location. See below.
data_old object or null The same location in the old 3-level format. Populated only when display_type=5; otherwise null.
data_new object or null The same location in the new 2-level format. Populated only when display_type=6; 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 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)

To get details for an entry point, pass its ref_id to 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 from the query point, in kilometers
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

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 and whether the API is enabled for the key in Manage API keys.

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 Reverse v4 on the Playground

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo