# Find a hotel by name

> Fuzzy search over the names of every hotel FX-Port knows.

Endpoint: `GET /hotels/name-search`

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

`GET /api/v1/hotels/name-search`

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

It tolerates typos, partial names and accents. Each hit carries the FX-Port hotel id to send as `hotel_id` to `get_rates` and `search_advanced`. Hits with a `match_score` below about 80 are often other hotels (a search for `Sofitel Algiers` also finds a hotel called `Algiers` in Las Vegas): show the score or keep the best few. The ids are the same in the sandbox and on live, and a hit is not necessarily bookable in the sandbox. `POST /hotels/search-by-name` takes the same fields as a JSON body.

## Request

### Query parameters

- `query` (string, required): The hotel name or a part of it, 2 to 100 characters.
- `limit` (integer, optional): Most hits to return, 1 to 100. A number outside that range, or text that is not a number, answers `400 invalid_limit`. Between 1 and 100. Default `10`.
- `min_score` (number, optional): Lowest match score to return, 0 to 100. A number outside that range, or text that is not a number, answers `400 invalid_min_score`. Between 0 and 100. Default `60`.
- `include_location` (boolean, optional): Add the address, city, country code and postal code to each hit. Default `true`.
- `include_details` (boolean, optional): Return the whole cached hotel document of each hit (about 26 KB each) instead of the summary. Default `false`.

### Example request

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

## Response

### 200: The hotels that match, best match first.

- `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.
- `query` (string): The text you searched for.
- `results_count` (integer): How many hotels are in `hotels`.
- `search_time` (string): Time the search took, as text with its unit, such as `0.061s`.
- `hotels` (array of object): The hotels that match, best match first.
  - `id` (string): The FX-Port hotel id: send it as `hotel_id`.
  - `name` (string): Name of the hotel.
  - `match_score` (number): How well the name matches your text, 0 to 100, two decimals. Below about 80 the hit is often another hotel. Between 0 and 100.
  - `match_type` (string): How the name matched. One of `exact`, `partial`, `fuzzy`.
  - `address` (string): Street address.
  - `city` (string): City.
  - `country_code` (string): ISO 3166-1 alpha-2 country code.
  - `postal_code` (string): Postal code; an empty string when unknown.

```json
{
  "environment": "sandbox",
  "query": "Sofitel Algiers",
  "results_count": 2,
  "search_time": "0.060s",
  "hotels": [
    {
      "id": "sofitel_algiers_hamma_garden",
      "name": "Sofitel Algiers Hamma Garden",
      "match_score": 83.39,
      "match_type": "partial",
      "address": "172, rue Hassiba Benbouali, Algiers",
      "city": "Algiers",
      "country_code": "DZ",
      "postal_code": "16014"
    },
    {
      "id": "algiers_hotel",
      "name": "Algiers",
      "match_score": 76.67,
      "match_type": "partial",
      "address": "2845 South Las Vegas Boulevard Las Vegas, South Las Vegas Boulevard, Las Vegas",
      "city": "Las Vegas",
      "country_code": "US",
      "postal_code": "89109"
    }
  ]
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_query` | 'query' must be 2 to 100 characters long. |
| 400 | `invalid_limit` | 'limit' must be at most 100. |
| 400 | `invalid_min_score` | 'min_score' must be a number between 0 and 100. |
| 400 | `bad_request` | Query cannot be empty |
| 422 | `validation_error` | Field required |
| 503 | `service_busy` | Hotel name search is busy right now. Retry in a couple of seconds. |

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

## Related guides

- [Hotel name search](https://fx-port.com/docs/hotels/name-search.md)