Booking.com

Search Booking.com properties

Search Booking.com properties for a destination and stay, with prices, ratings and review scores.

GET/v1/booking/search
x-api-keystringheader

API key (`sfk_...`)

Parameters
13
querystringrequiredquery

Where to stay: a city, region, district, landmark, airport or property name, e.g. `London`, `Cornwall` or `Heathrow Airport`.

min 1 chars · max 100 chars

checkInstringoptionalquery

Check-in date, `YYYY-MM-DD`, today or later. Default 14 days from today.

pattern: ^\d{4}-\d{2}-\d{2}$

checkOutstringoptionalquery

Check-out date, `YYYY-MM-DD`, after `checkIn` and at most 90 nights later. Default one night after check-in.

pattern: ^\d{4}-\d{2}-\d{2}$

adultsintegeroptionalquery

Adults travelling, 1 to 30. Default 2.

≥ 1 · ≤ 30

childrenAgesarrayoptionalquery

Ages of the children travelling, comma-separated, each 0 to 17, e.g. `5,9`. Omit when no children travel.

roomsintegeroptionalquery

Rooms needed, 1 to 30 and no more than the adults. Default 1.

≥ 1 · ≤ 30

currencystringoptionalquery

Currency of every price, as a three-letter code such as `USD`, `EUR`, `GBP` or `JPY`. Default `USD`.

languagestringoptionalquery

Language of names, labels and descriptions, as the site's own code: `en-us`, `en-gb`, `de`, `fr`, `es`, `it`, `ja`, `zh-cn` and so on. Default `en-us`.

countrystringoptionalquery

Visitor country, as a two-letter code such as `us`, `gb`, `de` or `jp`. The site decides from it whether prices include taxes. Default `us`, where prices are shown before taxes and charges.

filtersarrayoptionalquery

The site's own filters, comma-separated, e.g. `class=5` (5 stars), `review_score=90` (9+), `ht_id=204` (hotels) or `fc=2` (free cancellation). A first page lists them all in `availableFilters`. A filter the site does not apply to this search is answered with a 400, not charged, never with unfiltered results.

sortstringoptionalquery

Order. `price_lowest_first` (default) is the order the site pages consistently: two 300-row walks of the same search share 275 to 300 rows. A row with a deal can sit a few places below where its discounted price would put it, as on the site. `popularity` is the site's own "top picks" order, with its paid placements (`sponsored`), but the site reshuffles it between requests: two 300-row walks of London shared 163 to 292 rows, and one walk returned up to 43 rows twice (dropped, see `page.droppedCount`), so paging it misses rows. Also `price_highest_first`, `stars_highest_first`, `stars_lowest_first`, `stars_and_price`, `homes_first`, `distance` (as consistent as price for a city or a landmark, less for a region or a country) and `review_score`.

one of: popularity, homes_first, price_lowest_first, price_highest_first, stars_highest_first, stars_lowest_first, stars_and_price, distance, review_score

limitintegeroptionalquery

Rows per page, 1 to 100. Default 25.

≥ 1 · ≤ 100

cursorstringoptionalquery

Pass `page.nextCursor` from the previous response to get the next page. Omit it for the first page.

min 1 chars · max 1024 chars · pattern: ^[A-Za-z0-9_-]+$

Response fields
87

Endpoint-specific response payload.

datalookupStatus
string

`not_found` when the site matches the query to no destination.

one of: found, not_found

The matched destination; null when not found.

datadestinationid
integernullable

The site's id for the destination.

datadestinationtype
stringnullable

Destination type: `city`, `region`, `country`, `district`, `landmark`, `airport`, `hotel` and so on.

datadestinationname
stringnullable

Destination name as the site resolved the query.

datadestinationcountryCode
stringnullable

Two-letter country code, lower case.

The stay the prices are for, with every default filled in, so a later page or a repeat search can ask for the same stay.

datastaycheckIn
string

Check-in date, `YYYY-MM-DD`.

datastaycheckOut
string

Check-out date, `YYYY-MM-DD`.

datastaynights
integer

Nights.

datastayadults
integer

Adults.

Children's ages.

datastaychildrenAges[]
integeroptional
datastayrooms
integer

Rooms.

datastaycurrency
string

Currency the prices were asked in.

datastaylanguage
string

Language of the answer.

datastaycountry
string

Visitor country the answer is for.

datatotalCount
integernullable

Properties the site counts for the stay. It moves slightly from request to request as availability changes.

Properties on this page. A property the page before returned, or one the site repeats within the page, is left out and counted in `page.droppedCount`, so a page can hold fewer than `limit`.

dataproperties[]id
integer

Property id. Pass it as `propertyId` to the property reviews endpoint.

dataproperties[]name
string

Property name.

dataproperties[]url
stringnullable

Property page URL.

dataproperties[]pageName
stringnullable

The property's page name in its URL, e.g. `the-savoy`.

dataproperties[]accommodationType
stringnullable

Kind of property: `hotel`, `apartment`, `hostel`, `guest_house` and so on; null when unknown.

dataproperties[]accommodationTypeId
integernullable

The site's id for the kind of property.

dataproperties[]stars
numbernullable

Star or quality rating, 1 to 5; null when none.

dataproperties[]starsType
stringnullable

`stars` for an official or property-provided star rating, `squares` for the site's own quality rating of homes.

one of: stars, squares, other, null

dataproperties[]reviewScore
numbernullable

Guest review score, 1 to 10; null when not shown.

dataproperties[]reviewScoreLabel
stringnullable

The score's word, e.g. `Superb`.

dataproperties[]reviewCount
integernullable

Guest reviews counted in the score.

dataproperties[]locationScore
numbernullable

Guest score for the location, 1 to 10, when shown.

dataproperties[]externalReviewScore
numbernullable

Score from reviews collected elsewhere, for a property with few of its own, when shown.

dataproperties[]externalReviewCount
integernullable

Reviews behind `externalReviewScore`.

dataproperties[]address
stringnullable

Street address.

dataproperties[]city
stringnullable

City.

dataproperties[]countryCode
stringnullable

Two-letter country code, lower case.

dataproperties[]latitude
numbernullable

Latitude.

dataproperties[]longitude
numbernullable

Longitude.

dataproperties[]district
stringnullable

Area as the site shows it, e.g. `Westminster Borough, London`.

dataproperties[]distanceFromCentre
stringnullable

Distance as the site words it, e.g. `0.3 miles from centre`.

dataproperties[]publicTransport
stringnullable

Nearest station as the site words it, when shown.

dataproperties[]photo
stringnullable

Main photo URL. Link only; not hosted by Social Fetch.

Price of the stay; null when the property shows none.

dataproperties[]priceamount
numbernullable

Price of the whole stay for the rooms and guests asked, as the site shows it, in `currency`.

dataproperties[]pricecurrency
stringnullable

Currency of every amount here, e.g. `USD`.

dataproperties[]pricetext
stringnullable

The price as the site shows it, e.g. `US$205.12`.

dataproperties[]pricetaxesIncluded
booleannullable

Whether `amount` already includes taxes and charges. False when the site shows them on top (`taxesAndCharges`).

dataproperties[]pricetaxesAndCharges
numbernullable

Taxes and charges the site adds on top of `amount`; null when `amount` includes them.

dataproperties[]priceoriginalAmount
numbernullable

Price before a discount, when the site shows one; null otherwise.

dataproperties[]priceperNight
numbernullable

The site's average nightly room rate, in `currency`, null when the site does not send it: it sends it only to visitors from the US, and not for every property. It leaves out the per-night fees a property charges on top of the room (a resort, facility or tourism fee) that `amount` includes, so `amount` can be more than `perNight` times the nights: a New York stay at $30 a night in fees shows $90 more over three nights. Before taxes, like `amount` for a US visitor.

dataproperties[]pricepropertyAmount
numbernullable

The same stay in the property's own currency, when the site shows it.

dataproperties[]pricepropertyCurrency
stringnullable

The property's own currency, e.g. `GBP`.

dataproperties[]soldOut
booleannullable

Whether the property has nothing left for the stay.

dataproperties[]freeCancellation
booleannullable

Whether a free cancellation rate is offered.

dataproperties[]noPrepayment
booleannullable

Whether a rate without prepayment is offered.

dataproperties[]mealPlan
stringnullable

Meals included, as the site words it, e.g. `Breakfast included`.

The rooms or units the price is for.

dataproperties[]rooms[]name
stringnullable

Room or unit name.

dataproperties[]rooms[]count
integernullable

How many of it.

dataproperties[]rooms[]beds
integernullable

Beds in it.

dataproperties[]rooms[]bedrooms
integernullable

Bedrooms in it, for a home.

dataproperties[]rooms[]bathrooms
integernullable

Bathrooms in it, for a home.

dataproperties[]rooms[]area
stringnullable

Floor area as the site words it, when shown.

Facilities the site highlights on the row, e.g. `Fitness centre`.

dataproperties[]highlights[]
stringoptional
dataproperties[]sponsored
boolean

Whether the row is a paid placement.

dataproperties[]sustainabilityCertified
booleannullable

Whether the property holds a sustainability certification.

Filters the site offers for this search, on the first page only (empty on later pages).

dataavailableFilters[]field
string

Filter group key, e.g. `class` or `ht_id`.

dataavailableFilters[]title
stringnullable

Group name as the site shows it, e.g. `Property rating`.

The group's options.

dataavailableFilters[]options[]id
string

Pass it in `filters`, e.g. `class=5`.

dataavailableFilters[]options[]label
stringnullable

Option name as the site shows it, e.g. `5 stars`.

dataavailableFilters[]options[]count
integernullable

Properties it would leave, when shown.

dataavailableFilters[]options[]selected
boolean

Whether the search already applies it.

Pagination state for the current page.

datapagehasMore
boolean

Whether another page is available.

datapagenextCursor
stringnullable

Pass as `cursor` to get the next page; null on the last page.

datapageoffset
integer

Position of this page's first row in the full list.

≥ 0

datapagedroppedCount
integer

Rows the site sent for this page that were left out because the page before, or this page, already had them: the site's order moved between requests. This page holds that many fewer than it could; keep following `nextCursor`. 0 when nothing was dropped.

≥ 0

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metastale
booleanoptional

Present, and `true`, only when the source couldn't be reached and this is the last good answer for the same request instead, up to 24 hours old. Absent on every live answer.

one of: true

metafetchedAt
stringoptional

When a stale answer (`stale: true`) was originally fetched (ISO 8601, UTC). Absent on every live answer.

Code example

curl "https://api.socialfetch.dev/v1/booking/search?query=London" \
  -H "x-api-key: YOUR_API_KEY"

Responses

Booking.com properties for the stay.