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

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

{
  "status": "INVALID_REQUEST",
  "error_message": "query 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": "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": []
}