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

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":

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

On a server-side failure, status is UNKNOWN_ERROR:

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

Example:

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