# Reverse - v4

Source: https://maps.vietmap.vn/docs/map-api/reverse-version/reverse-v4/

[![Reverse]][Reverse]
 [Reverse]: https://maps.vietmap.vn/docs/assets/reverse-jpg.webp
 
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
!!! tip "Try it in the Playground"
    Call Reverse v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/reverse)** · or explore it on the [Live Map](https://tools.vietmap.vn/live/)

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration (Search + Reverse): **<a href="/docs/assets/agents/search-geocoding.txt" download="search-geocoding.txt">Search & Geocoding Agent Doc</a>** · 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
```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](#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](https://maps.vietmap.vn/docs/map-api/reverse-version/reverse-ver3.0/).

### Parameters

|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)||
|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](#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**
```ts
https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat=10.759221&lng=106.675901&display_type=6
```

[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/reverse?lat=10.759221&lng=106.675901&version=v4&display_type=6){ .md-button .md-button--primary }

**Response**

=== "Old, with `data_new`<br>`display_type=6`"

    ```json
    [
        {
            "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
            }
        }
    ]
    ```

=== "New, with `data_old`<br>`display_type=5`"

    ```json
    [
        {
            "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
        }
    ]
    ```

=== "Both, as two items<br>`display_type=4`"

    ```json
    [
        {
            "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
        }
    ]
    ```

=== "Response Old Format<br>`display_type=2`"

    ```json
    [
        {
            "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
        }
    ]
    ```
=== "Response New Format<br>`display_type=1`"

    ```json
    [
        {
            "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](https://maps.vietmap.vn/docs/map-api/place-v4/).

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](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 Reverse v4 on the Playground](https://tools.vietmap.vn/playground/reverse)**