# Read the content of many hotels by id

> Reads the content FX-Port holds for up to 200 hotels at once, by id.

Endpoint: `POST /hotels/search`

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

`POST /api/v1/hotels/search`

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

With `detail_level=minimal` (alias `mini`) each hotel is the MINI card of `search_advanced`: 13 fields, about 5 KB. Without it each hotel is the FULL document: 31 fields with every room type, about 35 KB. Use the mini form for lists and the full form (or `get_hotel_info`) for one hotel the user opened. The answer is a bare JSON array of snake_case hotels, not in the order you asked; an id that has no cached content is left out and queued for loading, it is not reported (use `missing_hotel_ids` of the search, or `get_hotel_info`, for those). An id made of digits (a JSON integer or text) is also looked up as the supplier's numeric `hid`; a hotel reached by both comes back once, and a digits-only id that matches nothing is not queued. `fields` returns only the top-level fields you list (`id` is always added). `images_limit` keeps the first N photos of each mini card. The call reads FX-Port's cache only: it never asks the supplier.

## Request

### Query parameters

- `detail_level` (string, optional): `minimal` (alias `mini`): the compact card. `full` (default): the whole document. One of `minimal`, `mini`, `full`. Default `full`.
- `fields` (string, optional): A comma separated list of top-level fields to return instead of a detail level, at most 40 (`id,name,star_rating`). Nested paths are not supported.
- `images_limit` (integer, optional): With `detail_level=minimal` and no `fields`: keep only the first N photos of each hotel, 0 to 30. In any other case it is ignored and the answer carries a `coerced_value` warning. A number outside 0 to 30 answers `400 invalid_images_limit`. Between 0 and 30.
- `detailLevel` (string, deprecated, optional): Legacy name: use `detail_level`. The detail level, in its older spelling. Use `detail_level`.
- `imagesLimit` (integer, deprecated, optional): Legacy name: use `images_limit`. The photo limit, in its older spelling. Use `images_limit`.

### Body

Required, JSON.

- `hotel_ids` (array of string, required): The ids of the hotels, at most 200. An id made of digits is also looked up as the supplier's numeric `hid`: `[8473727]` finds the hotel. Spaces around an id are trimmed. Duplicates are dropped; the answer does not follow your order. At most 200 items.
- `hotelIds` (array of string, deprecated, optional): Legacy name: use `hotel_ids`. The hotel ids, in their older spelling. Use `hotel_ids`.
- `ids` (array of string, deprecated, optional): Legacy name: use `hotel_ids`. The hotel ids, in their older spelling. Use `hotel_ids`.

### Example request

```bash
curl 'https://api.fx-port.com/api/v1/hotels/search?detail_level=minimal' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "hotel_ids": [
    "test_hotel_do_not_book",
    "hotel_honduras_maya_6"
  ]
}'
```

## Response

### 200: The hotels found: mini cards with `detail_level=minimal`, full documents otherwise. The `X-Results-Count` header counts them.

```json
[
  {
    "id": "test_hotel_do_not_book",
    "hid": 8473727,
    "name": "Test Hotel (Do Not Book) test",
    "kind": "Apartment",
    "address": "Avenida Roble, Frente al Mall Multiplaza, Tegucigalpa",
    "latitude": 14.079872,
    "longitude": -87.21677,
    "postal_code": null,
    "region": {
      "id": 3421,
      "country_code": "HN",
      "iata": "TGU",
      "name": "Tegucigalpa",
      "type": "City",
      "type_v2": "city"
    },
    "star_rating": 0,
    "images": [
      "https://cdn.worldota.net/t/{size}/extranet/b5/d3/b5d3d33394494c68321246882c1bd93a6832dcd5.jpeg",
      "https://cdn.worldota.net/t/{size}/extranet/15/44/15440558c952ec4c3488730d1563dc9e8d25832c.JPEG"
    ],
    "serp_filters": [
      "has_internet",
      "has_parking",
      "has_spa",
      "has_pets",
      "has_jacuzzi",
      "kitchen"
    ],
    "amenity_groups": [
      {
        "amenities": [
          "24-hour reception",
          "Early check-in",
          "Late check-out"
        ],
        "non_free_amenities": [],
        "group_name": "General"
      },
      {
        "amenities": [
          "Concierge services",
          "Dry-cleaning",
          "Shoe shine"
        ],
        "non_free_amenities": [
          "Dry-cleaning",
          "Shoe shine"
        ],
        "group_name": "Services and amenities"
      }
    ]
  }
]
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_detail_level` | 'detail_level' must be 'minimal' (alias 'mini') or 'full' (got 'tiny'). |
| 400 | `invalid_body` | 'body' can hold at most 200 hotel ids per request. |
| 400 | `invalid_images_limit` | 'images_limit' must be an integer from 0 to 30. |

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

## Related guides

- [Mini and full hotel data](https://fx-port.com/docs/hotels/hotel-data.md)