## 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

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

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

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

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

#### Example:

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