# Search locations

> Search cities and destinations by name and get back usable geo coordinates for hotel availability search.

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

Source: https://fx-port.com/docs/hotels/locations

Turn what a user typed (a city, an area, an airport) into places with coordinates. The `latitude` and `longitude` of the place the user picks are the input of the [geo search](https://fx-port.com/docs/hotels/search.md) (`search_advanced` with a `radius`), which lists the hotels around that point.

**Permission:** Read


> [!NOTE]
> This lookup finds **places**, not FX-Port hotels. To find one hotel by its name, use [Hotel name search](https://fx-port.com/docs/hotels/name-search.md). The `id` of a place is an id of the location provider and is **never** a hotel id you can send to `get_rates`.


## Query parameters

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

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | Yes | | 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 | No | `en` | 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. |
| `limit` | integer | No | `10` | Most places to return, 1 to 50. Places without coordinates are dropped before the limit is applied. |

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

A real answer of the sandbox, with the `raw` objects shortened:

~~~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"
      }
    }
  ]
}
~~~

| Field | Description |
|---|---|
| `success` | `true` when the lookup worked, also when nothing matches (`resultsCount` is then `0` and `locations` empty). |
| `resultsCount` | How many places are in `locations`. |
| `locations[].id` | The id of the place at the location provider: a city id, an airport code or a hotel id of the provider. Not a FX-Port hotel id. |
| `locations[].name`, `displayName`, `city`, `countryCode` | What to show in the list. `displayName` carries the context (`Tegucigalpa, Honduras`). |
| `locations[].latitude`, `longitude` | The only fields the [geo search](https://fx-port.com/docs/hotels/search.md) needs: send them as its `latitude` and `longitude`. |
| `locations[].type` | **Always** `location`. The kind of place is `raw.loctype`: `city`, `ap` (airport) or `hotel`. |
| `locations[].raw` | The record of the location provider, about 40 keys (`loctype`, `cityname`, `timezone`, the bounding box `box_*` ...). It is passed on as it is: unlisted keys can change, do not build on them. |

## From a place to a geo search

1. Show `displayName` for each place and let the user pick one. Results mix cities, airports and hotels: show an icon from `raw.loctype` if the list is long.
2. Send the `latitude` and `longitude` of the place to the [geo search](https://fx-port.com/docs/hotels/search.md) (`search_advanced`) with a `radius` in meters. The radius is **mandatory** and goes from 100 to 70,000: 5,000 to 15,000 is a good start for a city. A bigger radius means a bigger and slower answer.
3. When the user picked a **hotel** (`raw.loctype` is `hotel`), do not use its `id`. Search the hotel by name with [`name-search`](https://fx-port.com/docs/hotels/name-search.md) to get the FX-Port hotel id.

## Typeahead

- Wait about 300 ms after the last keystroke and cancel the request that is in flight.
- A first lookup of a text takes 1 to 2.5 seconds, a repeated one about a second. Keep the answers for the session of the user instead of asking again for the same text.
- The lookup is limited per IP address as well as per key: see [Rate limits](https://fx-port.com/docs/rate-limits.md).
- The answer is the same in the sandbox and on live.

## Names

The keys of this answer are camelCase (`resultsCount`, `displayName`, `countryCode`) and have no snake_case twin. Add `?naming=snake` to get every key in snake_case. See [Conventions and naming](https://fx-port.com/docs/conventions.md#naming).

## Errors

| HTTP | Code | Cause |
|---|---|---|
| `422` | `invalid_query` | `query` is blank, or longer than 64 characters. |
| `422` | `validation_error` | `query` is missing, or `limit` is outside 1 to 50. |
| `401`, `403` | | The key is missing, wrong or not allowed: [Authentication](https://fx-port.com/docs/authentication.md). |
| `429` | `rate_limit_exceeded` | Too many calls: [Rate limits](https://fx-port.com/docs/rate-limits.md). |

When its provider is slow or down, the lookup falls back to FX-Port's own records of places, so the `raw` object can then have other keys: one more reason not to build on it.

## Related


- [Geo search](https://fx-port.com/docs/hotels/search.md): The next step: the hotels around the coordinates you picked.
- [Hotel name search](https://fx-port.com/docs/hotels/name-search.md): Find one hotel by its name.
- [API reference: Search destinations](https://fx-port.com/docs/api/search-hotel-locations.md): Every field and error.