# Search destinations and get coordinates

> Turns the text a user typed (a city, an area, an airport, a hotel) into places with coordinates.

Endpoint: `GET /hotels/locations/search`

Source: https://fx-port.com/docs/api/search-hotel-locations

`GET /api/v1/hotels/locations/search`

Requires an API key with **Read** permission; a **Read+Write** key works too.

Pass the `latitude` and `longitude` of the place the user picks to `search_advanced`, with a `radius`. The results mix cities, airports and hotels of a location provider: the `id` is the provider's, not a FX-Port hotel id, and `type` is always `location` (the kind of place is `raw.loctype`). Places without coordinates are dropped. The answer is the same in the sandbox and on live. Cache the answers for a user's session and debounce typeahead calls (about 300 ms).

## Request

### Query parameters

- `query` (string, required): The text to look for: a city, an area, an airport or a hotel name, 1 to 64 characters once spaces and control characters are cleaned.
- `locale` (string, optional): Language of the names: `en`, `fr`, `ar`, `es`, `de`, `it`, `ru`, `tr`, `ja`, `ko` ... Written `ll` or `ll-RR` (`es-AR`); any other value answers in English. Default `en`.
- `limit` (integer, optional): Most places to return, 1 to 50. Between 1 and 50. Default `10`.

### Example request

```bash
curl 'https://api.fx-port.com/api/v1/hotels/locations/search?query=Tegucigalpa&limit=3' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: The places that match, best first. `locations` is empty when nothing matches.

- `environment` (string): The environment of the key that made the call: `sandbox` for fxp_test_ keys, `live` for fxp_live_ keys. Present in every JSON body. One of `sandbox`, `live`.
- `request_id` (string): The id of the request, also in the `X-Request-Id` header.
- `warnings` (array of object): Present only when the request used a previous spelling of a field or something the endpoint ignored.
  - `code` (string): What the warning is about. One of `deprecated_field`, `ignored_field`, `coerced_value`, `deprecated_value`, `deprecated_endpoint`.
  - `field` (string): The request field the warning is about.
  - `replacement` (string): The name to use instead, for `deprecated_*` warnings.
  - `message` (string): A sentence that says what happened and what to do.
  - `documentation_url` (string): Where the naming rules are explained.
- `success` (boolean): `true` when the lookup worked, also with no result.
- `query` (string): The text you searched for.
- `resultsCount` (integer): How many places are in `locations`.
- `locations` (array of object): The places that match, best first. Places without coordinates are dropped before `limit` is applied.
  - `id` (string): The id of the place at the location provider (a city id, an airport code or a hotel id of the provider). It is not a FX-Port hotel id.
  - `name` (string): Name of the place.
  - `displayName` (string): Name with its context, for a list.
  - `city` (string): City of the place.
  - `countryCode` (string): ISO 3166-1 alpha-2 country code.
  - `latitude` (number): Latitude: send it to `search_advanced`.
  - `longitude` (number): Longitude: send it to `search_advanced`.
  - `type` (string): Always `location`. The kind of place is `raw.loctype`: `city`, `ap` (airport), `hotel` ...
  - `raw` (object): The record of the location provider, about 40 keys (`loctype`, `lat`, `lng`, `cc`, `cityname`, `timezone`, `box_*`, `destination_images` ...). Best effort: unlisted keys can change.

```json
{
  "environment": "sandbox",
  "success": true,
  "query": "Tegucigalpa",
  "resultsCount": 2,
  "locations": [
    {
      "id": "20119",
      "name": "Tegucigalpa",
      "displayName": "Tegucigalpa, Honduras",
      "city": "Tegucigalpa",
      "countryCode": "HN",
      "latitude": 14.094204124743296,
      "longitude": -87.19410705810549,
      "type": "location",
      "raw": {
        "id": "20119",
        "displayname": "Tegucigalpa, Honduras",
        "loctype": "city",
        "cid": 107,
        "lat": 14.094204124743296,
        "lng": -87.19410705810549,
        "cc": "HN",
        "country": "Honduras",
        "timezone": "America/Tegucigalpa",
        "utc": "-06:00",
        "ap": "TGU"
      }
    },
    {
      "id": "TGU",
      "name": "Toncontin",
      "displayName": "Toncontin, Tegucigalpa, Honduras, (TGU)",
      "city": "Tegucigalpa",
      "countryCode": "HN",
      "latitude": 14.06088,
      "longitude": -87.2172,
      "type": "location",
      "raw": {
        "id": "TGU",
        "displayname": "Toncontin, Tegucigalpa, Honduras, (TGU)",
        "loctype": "ap",
        "cid": 107,
        "lat": 14.06088,
        "lng": -87.2172,
        "cc": "HN",
        "country": "Honduras",
        "airportname": "Toncontin",
        "ap": "TGU"
      }
    }
  ]
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 422 | `validation_error` | Input should be less than or equal to 50 |

See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react.

## Related guides

- [Search locations](https://fx-port.com/docs/hotels/locations.md)