## Text Search

This search API is typically used when the input is a full address.

### Request

#### Endpoint

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

#### Query params

| Param | Required | Description |
|  --- | --- | --- |
| `query` | Required | The search text, for example: `"lotte phu thuy"` |
| `radius` | Optional | Search radius around the focus point, in **meters**, max `50000`, for example: `5000` (= 5km) |
| `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/place/textsearch/json?query=75 Trương Công Định, Phường Phú Lợi, Thành phố Cần Thơ&has_deprecated_admin=true&radius=5000&key=YOUR_API_KEY'
```

### Response

`textsearch/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 place 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 a place 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 `focus.point.lat/lon` is passed | distance from the focus point, in km |
| `name` | always | place name |
| `formatted_address` | always | standardized full address |
| `old_formatted_address` | always | address before an administrative merge, or `""` if none |
| `geometry` | always | `location` (lat/lng) and `viewport` (northeast/southwest bounds) |
| `types` | always | array of place type classifications |


#### `error_message`

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

```json
{
  "status": "INVALID_REQUEST",
  "error_message": "query 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": "1:address:d2a3105720e541a49c5f3140c0fa19ab",
      "name": "75 Trương Công Định",
      "address_components": [
        {
          "long_name": "75",
          "short_name": "75",
          "types": [
            "street_number"
          ]
        },
        {
          "long_name": "Trương Công Định",
          "short_name": "Trương Công Định",
          "types": [
            "route"
          ]
        },
        {
          "long_name": "Phường Phú Lợi",
          "short_name": "Phường Phú Lợi",
          "types": [
            "administrative_area_level_2"
          ]
        },
        {
          "long_name": "Thành phố Cần Thơ",
          "short_name": "Thành phố Cần Thơ",
          "types": [
            "administrative_area_level_1"
          ]
        },
        {
          "long_name": "Việt Nam",
          "short_name": "VN",
          "types": [
            "country"
          ]
        }
      ],
      "formatted_address": "75 Trương Công Định, Phường Phú Lợi, Thành phố Cần Thơ, Việt Nam",
      "old_address_components": [
        {
          "long_name": "75",
          "short_name": "75",
          "types": [
            "street_number"
          ]
        },
        {
          "long_name": "Trương Công Định",
          "short_name": "Trương Công Định",
          "types": [
            "route"
          ]
        },
        {
          "long_name": "Phường 2",
          "short_name": "Phường 2",
          "types": [
            "administrative_area_level_3"
          ]
        },
        {
          "long_name": "Thành phố Sóc Trăng",
          "short_name": "Thành phố Sóc Trăng",
          "types": [
            "administrative_area_level_2"
          ]
        },
        {
          "long_name": "Tỉnh Sóc Trăng",
          "short_name": "Tỉnh Sóc Trăng",
          "types": [
            "administrative_area_level_1"
          ]
        },
        {
          "long_name": "Việt Nam",
          "short_name": "VN",
          "types": [
            "country"
          ]
        }
      ],
      "old_formatted_address": "75 Trương Công Định, Phường 2, Thành phố Sóc Trăng, Tỉnh Sóc Trăng, Việt Nam",
      "geometry": {
        "location": {
          "lat": 9.6029245,
          "lng": 105.9675911
        },
        "viewport": {
          "northeast": {
            "lat": 9.6038245,
            "lng": 105.9687911
          },
          "southwest": {
            "lat": 9.6020245,
            "lng": 105.96639110000001
          }
        }
      },
      "types": [
        "street_address"
      ]
    }
  ],
  "html_attributions": []
}
```