## Reverse Geocoding

Finds the place or address near a latitude/longitude pair.

### Request

#### Endpoint

```
https://dplace-api.themap.world/maps/api/geocode/json
```

#### Query params

| Param | Required | Description |
|  --- | --- | --- |
| `latlng` | Required | Coordinate of the place to look up, format `{lat},{lng}` (latitude first), for example: `10.7952219,106.7217912` |
| `radius` | Optional | Search radius around `latlng`, in **meters**, max `50000` |
| `size` | Optional | Number of results returned |
| `has_deprecated_admin` | Optional | `true` if you want to return old_formatted_address, old_address_components |


#### Example

```bash
curl --location 'https://dplace-api.themap.world/maps/api/geocode/json?latlng=10.792971,106.63975&radius=200&has_deprecated_admin=true&key=YOUR_API_KEY'
```

### Response

`geocode/json` wraps the response in the following top-level fields:

| Field | When present | Content |
|  --- | --- | --- |
| `status` | always | `OK`, `ZERO_RESULTS`, `INVALID_REQUEST`, or `UNKNOWN_ERROR` |
| `results` | always | array of address objects (empty array on `ZERO_RESULTS` / errors) |
| `error_message` | on `INVALID_REQUEST` / `UNKNOWN_ERROR` | error description |
| `html_attributions` | always | `[]` — no third-party attribution data |


#### `status`

| Value | Meaning |
|  --- | --- |
| `OK` | success, results found |
| `ZERO_RESULTS` | success but no results matched |
| `INVALID_REQUEST` | missing or invalid parameter (HTTP 400) |
| `UNKNOWN_ERROR` | server-side error: timeout, backend unreachable (HTTP 502/500) |


#### `results`

Each item in `results` is an address object with the fields shown in the example response body above:

| Field | When present | Content |
|  --- | --- | --- |
| `place_id` | always | unique identifier for the place |
| `confidence` | always | match confidence, from `0` to `1` |
| `distance` | always | distance from `latlng`, in km |
| `name` | always | place or address name |
| `address_components` | when available in the source data | array of `{long_name, short_name, types}` components of `formatted_address` |
| `formatted_address` | always | standardized full address |
| `old_address_components` | when `old_formatted_address` is non-empty | array of `{long_name, short_name, types}` components of `old_formatted_address` |
| `old_formatted_address` | always | address before an administrative merge, or `""` if none |
| `geometry` | always | `location` (lat/lng), `location_type`, and `viewport` (northeast/southwest bounds) when available |
| `types` | always | array of place type classifications |


#### `error_message`

When the request has an invalid parameter, `geocode/json` still returns HTTP 200 with `status: "INVALID_REQUEST"`:

```json
{
  "status": "INVALID_REQUEST",
  "error_message": "latlng is required",
  "results": [],
  "html_attributions": []
}
```

On a server-side failure, `status` is `UNKNOWN_ERROR`:

```json
{
  "status": "UNKNOWN_ERROR",
  "error_message": "backend unreachable",
  "results": [],
  "html_attributions": []
}
```

#### Example:

```json
{
  "status": "OK",
  "results": [
    {
      "place_id": "4:address:40b686b1b6cd4a20b13fa262912a7a8f",
      "confidence": 0.9,
      "distance": 0.004,
      "name": "216 Đường Trương Công Định",
      "address_components": [
        {
          "long_name": "216",
          "short_name": "216",
          "types": [
            "street_number"
          ]
        },
        {
          "long_name": "Đường Trương Công Định",
          "short_name": "Đường Trương Công Định",
          "types": [
            "route"
          ]
        },
        {
          "long_name": "Phường Tân Bình",
          "short_name": "Phường Tân Bình",
          "types": [
            "administrative_area_level_2"
          ]
        },
        {
          "long_name": "Thành phố Hồ Chí Minh",
          "short_name": "Thành phố Hồ Chí Minh",
          "types": [
            "administrative_area_level_1"
          ]
        },
        {
          "long_name": "Việt Nam",
          "short_name": "VN",
          "types": [
            "country"
          ]
        }
      ],
      "formatted_address": "216 Đường Trương Công Định, Phường Tân Bình, Thành phố Hồ Chí Minh, Việt Nam",
      "old_address_components": [
        {
          "long_name": "216",
          "short_name": "216",
          "types": [
            "street_number"
          ]
        },
        {
          "long_name": "Đường Trương Công Định",
          "short_name": "Đường Trương Công Định",
          "types": [
            "route"
          ]
        },
        {
          "long_name": "Phường 14",
          "short_name": "Phường 14",
          "types": [
            "administrative_area_level_3"
          ]
        },
        {
          "long_name": "Quận Tân Bình",
          "short_name": "Quận Tân Bình",
          "types": [
            "administrative_area_level_2"
          ]
        },
        {
          "long_name": "Thành phố Hồ Chí Minh",
          "short_name": "Thành phố Hồ Chí Minh",
          "types": [
            "administrative_area_level_1"
          ]
        },
        {
          "long_name": "Việt Nam",
          "short_name": "VN",
          "types": [
            "country"
          ]
        }
      ],
      "old_formatted_address": "216 Đường Trương Công Định, Phường 14, Quận Tân Bình, Thành phố Hồ Chí Minh, Việt Nam",
      "geometry": {
        "location": {
          "lat": 10.793002,
          "lng": 106.639786
        },
        "location_type": "ROOFTOP",
        "viewport": {
          "northeast": {
            "lat": 10.793902,
            "lng": 106.640986
          },
          "southwest": {
            "lat": 10.792102,
            "lng": 106.638586
          }
        }
      },
      "types": [
        "street_address"
      ]
    }
  ],
  "html_attributions": []
}
```