Try Cars out!

If you are a Booking.com Managed Affiliated Partner and are part of the early access pilot program you can start trying our Cars API in your client application

Quick guide

Follow this quick guide to start playing around with our /cars API endpoints.
By building requests based on a basic use case you will learn how to integrate with your application so that a traveller can:

Search for car rental provided by Booking.com.
Look at and navigate through results.

When the traveller sees a vehicle and supplier location that meets their requirements, and decides to book, is redirected to Booking.com to complete the booking.

Before you start

Before start trying out our car rental endpoints, make sure that:

Checklist
☑	You are a registered Booking.com Managed Affiliate Partner and are part of the early access Cars pilot program.
☑	Your dedicated Account Manager has granted you access to Partner Centre (after signing agreed contract).
☑	From the Partner Centre you have generated: A valid API key that allows you to use the endpoints. An unique identifier id (`X-Affiliate-Id`) that identifies your requests.
☑	You have a suitable API testing tool, such as cURL or Postman.

For more information, see Authentication and authorisation section.

Use case

This use case represents a typical Cars API scenario:

A traveller visiting your website wants to add car rental for their upcoming holiday in Edinburgh, Scotland.
They want to book a medium sized car for 8 days.
The traveller is in the Netherlands and is using your website from their mobile phone.

To get familiar with the Car API flow and the endpoints involved, take this use case as an example in every step of this guide.

Attention

Do not forget to authenticate every call that you make to our endpoints by using your API key - Token and your X-Affiliate-Id parameter.
For more information, see the Authentication and authorisation section.

Step 1 - Search for available vehicles

→ Use the /cars/search request to let travellers search for car rentals and look at the price and list of available vehicles for the route they are interested on.

Key parameters	Description	Recommendation
`booker.country`	Specify the country from which the search request is made. This is required to ensure that the response complies with relevant laws on the display of taxes and fees.	Get your two-letter country code using the List countries endpoint. In this case for the use case provided, use (`nl`). Note: The country code must always be in lowercase.
`currency`	Specify the three-letter code that uniquely identifies the country's monetary currency.	For this example, you will use "EUR" as the traveller is in the Netherlands. You can check the full list of currency codes here.
`driver age`	This field determines if age related fees are required or not.	If the customer’s age is known, send the actual age (Must be a number between 18 and 99) If age is unknown, prompt the traveller to select a default age range or submit their age outside this range. When the default age range is chosen, the age submitted in the search request is 30.
`route.pickup`/ `dropoff`	Specify the traveller's requested pickup and dropoff dates and times.	Use the YYYY-MM-DD format.
`route.location`	Specify location where pickup/dropoff is taking place.	Use the IATA three-letter code to identify an airport. In this case, would be: EDI for Edimburgh airport. Find your IATA codes here. Or add the latitude/longitude coordinates (see example below)

Location

Currently only airports are accepted. No train stations or other locations are supported.

For the provided use case you should create a request body similar to this example:

{
  "booker": {
    "country": "nl"
  },
  "currency": "EUR",
  "driver": {
    "age": 36
  },
  "route": {
    "pickup": {
      "datetime": "2024-09-01T10:00:00",
      "location": {
        "airport": "EDI"
      }
    },
    "dropoff": {
      "datetime": "2024-09-08T11:05:00",
      "location": {
        "airport": "EDI"
      }
    }
  }
}

Example with latitude and longitude coordinates:

{
  "pickup": {
    "datetime": "2024-09-01T11:05:00",
    "location": {
      "coordinates": {
        "latitude": 52.309456,
        "longitude": 4.762266
      }
    }
  }
}

→ Try it yourself

Step 2 - Get details

Before you show the search results to the traveller, you need to get additional content about each vehicle, the supplier and the depot(s).

You can do it in two different ways:

a) Using the local cache of static data.

b) Alternatively you can call the static data endpoints:

Endpoint	Use it to ...
/cars/details	Get additional information about the available vehicles.
/cars/suppliers	Return the list of available cars suppliers.
/cars/depots	For information about the pickup and dropoff locations returned in the cars/search response.

Step 3 - Display your search results page

You now have the necessary information to display the search results to the traveller.

Use data from both the cars/search and car/details responses to provide the level of detail suited to your business needs.

Recommendations

Limiting the number of results

To improve the search experience, consider limiting the maximum number of results displayed.

{
  "last_modified": "2024-12-01T11:05:00+00:00",
  "maximum_results": 100
}

Keeping content up-to-date

For static content (e.g., data from the car/details endpoint), we recommend checking the last_modified timestamp to ensure the information is up-to-date.

Timestamps follow the ISO 8601 standard, with the format: YYYY-MM-DDTHH:MM:SSZ (UTC only).

Show supplier logo

When displaying supplier results, consider showing the supplier’s logo alongside their name.

This helps travellers easily recognise the supplier and makes their decision-making process smoother.

Display scores

We also recommend showing the total score, as well as the breakdown of scores for each depot, on the search results page.

This can significantly aid the traveller in their booking decision.

Refer to the endpoints examples page for tips and samples.

Step 4 - Redirect the customer to complete the booking

After a traveller has chosen the vehicle they want to book, you should redirect them to the URL (either app or web link) returned in your /cars/search response.

Go to the /cars/search response.
Copy the returned Booking URL.
Redirect the traveller to the selected URL.

For example:

"url": {
  "app": "booking://cars/search?affiliate_id=xxxxx&driver_age=25&do_time=2024-06-22T10:00&do_loc_iata=MAN&pu_time=2024-06-20T10:00&pu_loc_iata=LHR&pu_loc_name=London+Heathrow+Airport&expand_search=false",
  "web": "https://cars.booking.com/search-results?vehicleId=699340901&vehicleInfo.vehicle.id=699340901&aid=xxxxxxx&prefcurrency=USD&preflang=en&driversAge=25&doHour=10&doMinute=0&doDay=22&doMonth=6&doYear=2024&dropLocationIata=MAN&puHour=10&puMinute=0&puDay=20&puMonth=6&puYear=2024&locationIata=LHR&locationName=London+Heathrow+Airport"
}

Curious to know more?

Refer to the endpoints examples section for more tips and suggestions.
Ready to migrate your integration? Check out our Migration guide to smoothly transition to the Demand API car endpoints.