POST /v1/search/stays

Ranked discovery search across millions of properties.

Ranked discovery across the full inventory. Returns up to 100 properties per page with per-OTA offers, live availability, and a cursor for pagination.

Endpoint

POST /v1/search/stays

Parameters

Parameter	Type	Description
`location` *	Location	destination_id, coordinates (+ radius), bbox, or property_id.
`dates` *	Dates	ISO 8601 check-in / check-out.
`guests` *	Guests	Adults, children ages, rooms.
`filters`	object	`price_max_eur`, `min_rating`, `property_types[]`.
`sort`	enum	`score_desc` (default), `price_asc`, `rating_desc`, `conversion_desc`.
`page`	object	`limit` (1-100, default 20), `cursor`.

* required

Request

curl -X POST https://api.b2a.bluepillow.com/v1/search/stays \
  -H "Authorization: Bearer $B2A_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"type": "destination_id", "value": "dest_5f3a..."},
    "dates":    {"check_in": "2026-06-10", "check_out": "2026-06-13"},
    "guests":   {"adults": 2},
    "filters":  {"price_max_eur": 300, "min_rating": 4.0,
                 "property_types": ["hotel", "aparthotel"]},
    "sort":     "score_desc",
    "page":     {"limit": 20}
  }'

Response 200

{
  "results": [
    {
      "id": "prop_abc123",
      "name": "Hotel Blue Sky",
      "property_type": "hotel",
      "rating": 4.7,
      "location": {"lat": 41.91, "lon": 12.48, "city": "Rome", "country": "IT"},
      "amenities": ["wifi", "spa"],
      "ota_coverage": ["Booking", "Expedia"],
      "offers": [{"ota": "Booking", "amount": 210.00, "currency": "EUR", "rooms_left": 2}],
      "price": {"amount": 210.00, "currency": "EUR", "ota": "Booking"},
      "availability_status": "available"
    }
  ],
  "page":     {"next_cursor": "eyJv...", "total_estimate": 184},
  "metadata": {"price_as_of": "2026-05-28T10:14:33Z", "otas_queried": 8, "request_id": "req_..."}
}

Errors

400 invalid_request · 401 authentication_failed · 429 rate_limited