Place Autocomplete

Helps users search for a place without typing the full search term.

Request

Endpoint

https://dplace-api.themap.world/maps/api/place/autocomplete/json

Query params

Param	Required	Description
`input`	Required	The text being typed, for example: `"lotte phu thuy"`
`location`	Optional	Coordinate to bias results toward nearby places, format `{lat},{lng}` (latitude first), for example: `10.7952219,106.7217912`
`size`	Optional	Number of suggestions returned
`radius`	Optional	Defines the distance (in meters) within which to return place results. You may bias results to a specified circle by passing a location and a radius parameter. In meters, max `50000`, for example: `5000` (= 5km). Default value is `20000`, default value is recommended. Requires `location` — sent without it, `radius` is ignored
`strictbounds`	Optional	Returns only results within the `location`+`radius` circle, instead of biasing toward it. `true`/`1` to enable; any other value (including omitted) is `false`. Requires `radius`
`locationbias`	Optional	Soft-prefer results in an area — results outside it can still be returned, just ranked lower. Format `circle:{radius meters}@{lat},{lng}`, for example: `circle:2000@10.7,106.6`. `rectangle:...` is not supported for this param. Ignored if `radius` is also sent (`radius` wins); if `locationrestriction` is also sent, `locationrestriction` wins
`locationrestriction`	Optional	Hard-restrict results to an area — results outside it are excluded. Format `circle:{radius meters}@{lat},{lng}` or `rectangle:{south},{west}\|{north},{east}`, for example: `rectangle:10.6,106.5\|10.8,106.7`. Ignored if `radius` is also sent (`radius` wins); wins over `locationbias` if both are sent
`types`	Optional	One or more place categories to filter suggestions, separated by `\|`, for example: `restaurant\|cafe`. A type the system has no data for returns empty results, not an error
`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/place/autocomplete/json?input=lotte phu thuy&location=10.773220,106.725404&has_deprecated_admin=true&key=YOUR_API_KEY'

Response

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

Field	When present	Content
`status`	always	`OK`, `ZERO_RESULTS`, `INVALID_REQUEST`, or `UNKNOWN_ERROR`
`predictions`	always	array of suggestion objects (empty array on `ZERO_RESULTS` / errors)
`error_message`	on `INVALID_REQUEST` / `UNKNOWN_ERROR`	error description

`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)

`predictions`

Each item in predictions is a suggestion object with the fields shown in the example response body above:

Field	When present	Content
`place_id`	always	unique identifier for the place
`distance`	when `location` is passed	distance from the biasing coordinate, in km
`description`	when available in the source data	complete location description
`terms`	when available in the source data	array of `{offset, value}` components of `description`
`structured_formatting`	when available in the source data	`main_text`, `secondary_text`, and their `*_matched_substrings`
`matched_substrings`	always	array of `{offset, length}` marking where `input` matched in `description`
`formatted_address`	always	standardized full address
`old_formatted_address`	always	address before an administrative merge, or `""` if none
`types`	always	array of place type classifications

`error_message`

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

{
  "status": "INVALID_REQUEST",
  "error_message": "input is required",
  "predictions": []
}

On a server-side failure, status is UNKNOWN_ERROR:

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

Example:

{
  "status": "OK",
  "predictions": [
    {
      "place_id": "4:address:423974e970dd4ebc8366ee069f4b86d6",
      "distance": 3.414,
      "description": "6 Đường Hoàng Bật Đạt, Phường Tân Sơn, Thành phố Hồ Chí Minh, Việt Nam",
      "terms": [
        {
          "offset": 0,
          "value": "6 Đường Hoàng Bật Đạt"
        },
        {
          "offset": 23,
          "value": "Phường Tân Sơn"
        },
        {
          "offset": 39,
          "value": "Thành phố Hồ Chí Minh"
        },
        {
          "offset": 62,
          "value": "Việt Nam"
        }
      ],
      "structured_formatting": {
        "main_text": "6 Đường Hoàng Bật Đạt",
        "secondary_text_matched_substrings": [],
        "secondary_text": "Phường Tân Sơn, Thành phố Hồ Chí Minh, Việt Nam",
        "main_text_matched_substrings": [
          {
            "offset": 8,
            "length": 13
          }
        ]
      },
      "matched_substrings": [
        {
          "offset": 8,
          "length": 13
        }
      ],
      "formatted_address": "6 Đường Hoàng Bật Đạt, Phường Tân Sơn, Thành phố Hồ Chí Minh, Việt Nam",
      "old_formatted_address": "6 Đường Hoàng Bật Đạt, Phường 15, Quận Tân Bình, Thành phố Hồ Chí Minh, Việt Nam",
      "types": [
        "street_address"
      ]
    }
  ]
}