# Find a hotel by name (JSON body)

> The same search as GET /hotels/name-search, with the parameters in a JSON body.

Endpoint: `POST /hotels/search-by-name`

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

`POST /api/v1/hotels/search-by-name`

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

Use whichever your client prefers. A body error answers `400`: `missing_field` for a missing `query`, `invalid_query` for the text, `invalid_limit` and `invalid_min_score` for the numbers, and `bad_request` with a message that names the field for the two booleans; the GET form answers `422` for a query parameter that is missing. A `limit` above 100 is capped at 100 and the answer carries a `coerced_value` warning; the GET form refuses it with `invalid_limit`.

## Request

### Body

Required, JSON.

- `query` (string, required): The hotel name or a part of it, 2 to 100 characters. Typos and accents are tolerated.
- `limit` (integer, optional): Most hits to return, 1 to 100. A larger number is capped at 100, with a `coerced_value` warning. A whole number written as text (`"10"`) is read as the number, with the same warning. Between 1 and 100. Default `10`.
- `min_score` (number, optional): Lowest match score to return, 0 to 100. A number written as text (`"60"`) is read as the number, with a `coerced_value` warning. Between 0 and 100. Default `60`.
- `include_location` (boolean, optional): Add the address, city, country code and postal code to each hit. Ignored with `include_details`. The text `true` or `false` (also `1`, `0`, `yes`, `no`, `on`, `off`) is read as the boolean, with a `coerced_value` warning; `null` means the default. Default `true`.
- `include_details` (boolean, optional): Return the whole cached hotel document for each hit instead of the summary. About 26 KB per hit. Text is read as in `include_location`. Default `false`.

### Example request

```bash
curl https://api.fx-port.com/api/v1/hotels/search-by-name \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Sofitel Algiers",
  "limit": 3,
  "min_score": 60,
  "include_location": true,
  "include_details": false
}'
```

## 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 | `missing_field` | Missing required field: 'query' |
| 400 | `invalid_query` | 'query' must be 2 to 100 characters long. |
| 400 | `invalid_limit` | 'limit' must be a positive integer. |
| 400 | `invalid_min_score` | 'min_score' must be a number between 0 and 100. |
| 400 | `bad_request` | 'include_details' must be a boolean |
| 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)