Rate limiting

This section provides an overview of rate limiting in the Demand API, with practical strategies to help you integrate efficiently while staying within the usage limits.

Understanding rate limiting in Demand API

To ensure the stability and availability of the Demand API, Booking.com enforces rate limits on the number of requests a partner account can send per minute to any V3 Demand API endpoint.

Please contact your Account Manager for details on your partner account's specific rate limit.

Rate limiting is a measure to prevent system overload and ensure equitable resource distribution among all partners.

When an account exceeds the rate limit, the API responds with a 429 - Too many requests error indicating that the allowed request quota has been reached.
Access is then temporarily restricted for a brief period (typically 1 minute), after which the request counter is reset, and API calls are once again accepted.

Optimise API Usage

To minimise disruptions from rate limiting, structure your integration efficiently to ensure you only retrieve the data you need.

These are some strategies and best practices that can help optimise your requests:

Define your caching strategy

Avoid unnecessary requests by caching data. Determine what to cache, how to store it, and how often to refresh it.

If cache refreshes lead to a surge in requests, consider spreading the load to avoid spikes.

Recommendation:	Cache data effectively
Why?	Caching avoids repeatedly querying the same data.
How?	Implement a caching mechanism that stores relevant data for a period. Decide how frequently to refresh the cache based on how often the data changes. For example, if certain accommodations' data remains static (like images), you can cache this information and refresh it less frequently.
Best practice	Make sure the cache is refreshed in intervals that are appropriate for your use case to ensure that your data is not outdated.

Use filters and "extras" field

These features help optimise the data returned, ensuring that only relevant information is retrieved.

Recommendation:	Optimise filters
Why?	Using filters allows you to reduce the amount of data returned by each request, improving efficiency.
How?	Use specific filters such as "price" range or "location", to narrow down your results and only retrieve the necessary data.
Example	In /accommodations/search requests, use the distance filters to get a list of accommodations located on a specific area, rather than retrieving the entire dataset.

Example - Search request using the distance filters:

{
  "coordinates": {
    "latitude": 52.3676,
    "longitude": 4.9041,
    "radius": 5
  },
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2025-03-09",
  "checkout": "2025-03-10",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

Recommendation:	Use “Extras” field
Why?	Using the "extras" field in your requests allows you specify which additional data you need fo your use case, so you can minimise the amount of information returned.
How?	You can use this field in accommodations/search and accommodations/details endpoints to retrieve information about products or extra charges, and also facilities, photos, policies, etc. This reduces the payload size and ensures faster response times.
Example	When looking at the accommodations/details you can select only the "extra" data of your interest, such as "facilities" or "photos".

Example - "Extras field" in accommodations/details request:

{
  "accommodations": [
    10004
  ],
  "extras": [
    "description",
    "facilities",
    "payment",
    "photos",
    "policies",
    "rooms"
  ],
  "languages": [
    "en-gb"
  ]
}

Leverage pagination

Recommendation:	Implement pagination
Why?	When requesting large datasets, pagination can help limiting the number of results returned per request.
How?	Use the `rows` parameter to control how many results are returned per page. This is especially useful for endpoints that may return large sets of results (e.g., accommodation listings).
Best practice	If you anticipate handling large datasets, implement pagination handling in your integration, which will allow you to fetch data incrementally without overwhelming the API.

Refer to the Filters and pagination guide for examples and best practices.

Implement a backoff strategy

Recommendation:	Implement backoff strategy
Why?	When your integration exceeds the API's rate limit and receives a 429 Too Many Requests error, avoid retrying too quickly. Bombarding the server with retries can worsen the situation, leading to further violations or temporary bans.
How?	Gradually increase the waiting time between retry attempts after receiving a 429 error. This helps reduce the frequency of requests and minimizes chances of hitting the rate limit again.
Best practice	Implement an exponentially increasing delay between retries (e.g., 1s, 2s, 4s, 8s, etc.) after each 429 response. Limit the maximum number of retries and cap the total delay time. Continuously monitor and adjust based on performance.

Distribute requests over time

If your system generates large numbers of requests, try to distribute them evenly over time to prevent sudden spikes that could lead to rate-limiting errors.

Consider batch processing or delaying requests during peak times.

Monitore traffic and rate limiting alerts

Booking.com enforces rate limits on the Demand API to maintain system stability and ensure fair access for all users, while still allowing integrations to operate smoothly within normal traffic levels.

However, there may be times when your integration needs to send more requests than usual.

These increases in request volume can happen for various reasons, including:

One-time spikes in traffic, such as when building or updating a large cache of static content.
Regular increases due to natural growth in the usage of your application.
Sustained traffic growth over time as your system scales.

It is essential to actively monitor your API traffic usage actively and identify any rate-limiting errors (e.g., HTTP 429 - Too many requests) to understand when you're nearing or exceeding the allowed limits.

If you anticipate a significant increase in request volume—such as scaling by a factor of 2 or more—:

Contact Booking.com as early as possible.
Provide details about your expected traffic increase, and discuss potential solutions or adjustments to your rate limits to avoid disruptions.

By staying proactive and monitoring your traffic usage, you can ensure that your integration continues to function smoothly without hitting rate limits unexpectedly.

Rate limiting in Sandbox

In the Sandbox environment of the Booking.com Demand API, rate limits are implemented to ensure fair use of resources and maintain the performance of the system.

As such, the following non-configurable rate limit applies:

Maximum requests per minute (RPM) - 50 requests.

If you exceed this limit, the API will return a 429 Too many requests error.

Rate limiting in cars

When using the cars/search endpoint, please note that there is a rate limit set at 3000 requests per minute.

This limit ensures the stability and availability of the Car rentals endpoints, preventing system overload and ensuring fair access for all partners.

Keep an eye on your request volume to understand when you're nearing the rate limit. This will allow you to adjust your request frequency or optimise your usage accordingly.

Recommendation

If you consistently approach the 3000 requests per minute limit, consider reaching out to your Booking.com Account Manager to discuss potential options for adjusting your rate limit.

By adhering to these best practices, you can optimise your integration, reduce the likelihood of encountering rate-limiting errors, and ensure smooth operation when using the Demand API endpoints.

Refer to the Error handling guide for rate limiting errors and best practices.
Explore the Filters and pagination guide for further descriptions and examples.