# Search for car rentals **Learn how to use the /cars/search endpoint to find and retrieve car rentals that match travellers’ preferences, routes, and date ranges.** → Use the [/cars/search](/demand/docs/open-api/demand-api/cars/search) endpoint to retrieve a list of cars available within a given route, date range, or set of filters. This endpoint: * Covers a wide range of traveller needs — from budget-friendly city cars to luxury SUVs. * Finds and returns the optimum set of matching rental options so travellers can quickly choose the right vehicle. * Increases the likelihood of converting searches into bookings by showing relevant, well-priced products. This guide explains how to structure your request, filter and sort results, handle pagination, and interpret the search response. ## How it works The **request** defines search parameters to find available cars. The **response** returns a list of matching cars, including prices, policies, and metadata about the search results. Example use case: > *Retrieve cars in Amsterdam Airport Schiphol (AMS) available between 5–10 November 2025, filtered by automatic transmission, limited mileage and price.* ### Search request example v3.1 request **3.1 request example:** ```json { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal" }, "route": { "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "airport": "AMS" } }, "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "airport": "AMS" } } }, "payment": { "timings": ["pay_now"] } } ``` v3.2 request **v3.2 with new payment timing:** ```json { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal" }, "route": { "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "airport": "AMS" } }, "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "airport": "AMS" } } }, "payment": { "timings": ["pay_online_now"] } } ``` ### Search inputs | Field | Format | Required | Description | | --- | --- | --- | --- | | `booker.country` | string | Yes | Two-letter country code (ISO 3166-1 alpha-2) in lowercase. Determines traveller context for pricing and taxes. Get this code running the [/common/locations/country](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries) endpoint. | | `driver.age` | integer | Yes | Age of the driver (18–99). Affects availability and price. Minimum: 18 - Maximum 99. | | `currency` | string | Yes | ISO 4217 code (e.g. `EUR`). Currency for pricing. Retrieve codes using /common/payments/currencies. | | `route.pickup` | object | Yes | Pick-up location and datetime. ISO 8601 date and time format: `YYYY-MM-DDThh:mm:ss`. See location options below. | | `route.dropoff` | object | Yes | Drop-off location and datetime. | | Location options | object | Airport code / coordinates / city ID | Specify pick-up and drop-off by: • Airport: `{ "airport": "AMS" }` • Coordinates: `{ "coordinates": { "latitude": 52.309456, "longitude": 4.762266 } }` • City ID: `{ "city": -2140479 }` (Use [/common/locations/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities) for the full list.) | | Filters | object | No | See section below for optional filters (transmission, mileage, depot type, car category, number of seats, suppliers). | | Payment.timings | array of strings | No | • In v3.1 use `pay_now`, `part_pay`, `pay_local` • In v3.2 use `pay_online_now`, `pay_partial_online_now` and `pay_at_pickup`. Filter by payment timing. | | `maximum_results` | integer | No | 10–500, multiple of 10, default 100. Max number of results. | | Pagination / sorting | object | No | `sort.by` (`price`, `distance`, `review_score`), `sort.direction` (`ascending`, `descending`). Use `page` for pagination token from `metadata.next_page`. | * Only one of airport, coordinates, or city should be used per pickup/dropoff location. * `pickup.datetime` must be ≤ `dropoff.datetime`. * Maximum results is 500. ### Optional filters Filters help tailor results to traveller preferences and vehicle features. Examples: * `air_conditioning` – true (only cars with AC) or false. * `car_categories` – Filter by car type (e.g., "compact", "suvs", "premium"). * `depot_location_type` – Location of the rental depot (e.g., "in_terminal", "downtown"). * `mileage_type` – "limited" or "unlimited". * `number_of_seats` – Minimum required seats. * `transmission_type` – "automatic" or "manual". * `supplier_ids` – Retrieve cars from specific suppliers (max 10 IDs). Payment filters - Narrow results based on the desided payment timing: * `pay_now` – Full online payment at booking. * `part_pay` – Partial payment upfront, balance later. * `pay_local` – Payment at the depot directly. v3.2 payment timings If you are using v3.2 the payment timings are: `pay_online_now`, `pay_partial_online_now` and `pay_at_pickup` #### Example - Filters ```json "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal", "car_categories": ["economy", "compact"], "number_of_seats": 5, "supplier_ids": [7455, 1234] } ``` #### Example - Pagination and sorting ```json "maximum_results": 50, "sort": { "by": "price" }, "page": "eyJhbGciOiJIUzI1NiJ9..." ``` See the [pagination guide](/demand/docs/development-guide/pagination) for more details. ## Response The response contains a list of matching cars and metadata about the search: v3.1 response **3.1 response example:** ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "P7D" } }, "damage_excess": 3000, "deposit": 1500, "insurance_package": "basic", "fuel": "return_same", "mileage": { "distance": 200, "distance_unit": "kilometers", "amount": 12.54, "type": "limited" }, "payment": { "timing": "pay_now" }, "theft_excess": 3000 }, "price": { "total": "121.90", "currency": "EUR", "extra_charges": [ { "charge": "aged_fee", "total_amount": 21.9 }, { "charge": "one_way_fee", "total_amount": 50 } ] }, "route": { "dropoff": { "depot": 112314, "depot_location_type": "airport_hotel" }, "pickup": { "depot": 112314, "depot_location_type": "airport_hotel" } }, "supplier": 7455, "url": { "app": "booking://page", "web": "https://example.com" } } ], "metadata": { "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im1heGltdW1fcmVzdWx0cyI6MTAsIm9mZnNldCI6MTB9LCJhdWQiOiJDQVJTX1NVUFBMSUVSUyIsImV4cCI6MTY4MzY0NzMwNX0.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A", "total_results": 122 }, "search_token": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoidXMifX0sImF1ZCI6Ii9ob3RlbHMvc2VhcmNoIiwiZXhwIjoxNzUwMDAwMDAwfQ.XYZ123AbcDefGHIjklMNOpqrsTUVwxYZ456789" } ``` v3.2 response **New structure example (v3.2):** ```json { "request_id": "string", "data": [ { "car": 12345, "offer": 67890, // NEW in v3.2: required for /cars/availability "categories": [ // NEW "large", "suvs" ], "deal": { "discount_percentage": 10, "public_price": 200.0, "tags": ["black_friday"] }, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "BEFORE_PICKUP", "duration": "PT48H" } }, "damage_excess": { // CHANGED: now object with amount + currency "amount": 500.0, "currency": "EUR" }, "deposit": { // CHANGED: now object with amount + currency "amount": 100.0, "currency": "EUR" }, "theft_excess": { // CHANGED: now object with amount + currency "amount": 1000.0, "currency": "EUR" }, "insurance_package": "inclusive", "fuel": "return_same", "mileage": { // CHANGED: amount now object with currency "type": "limited", "distance": 500, "distance_unit": "kilometers", "amount": 50.0, "currency": "EUR" }, "payment": { "timing": "pay_online_now" // UPDATED enum } }, "price": { "currency": "EUR", "extra_charges": [ { "charge": "age_fee", "total_amount": 10.0 } ], "total": 210.0 }, "route": { "pickup": { "depot": 5944 // depot_location_type REMOVED in v3.2 }, "dropoff": { "depot": 5944 // depot_location_type REMOVED in v3.2 } }, "supplier": 9876, "url": { "app": "https://app.booking.com/cars/123", "web": "https://cars.booking.com/123" } } ], "metadata": { "next_page": null, "total_results": 1 }, "search_token": "encoded_string_here" } ``` Product coverage * Not all cars visible on the Booking.com website are available via the Demand API. * The API delivers a consistent, integrator-friendly subset of inventory optimised for connected trip solutions. ### The search_token The `search_token` stores the search context associated with the request. * Include it in your v3.2 Beta requests, to cars/availability, orders/preview and orders/create endpoints. * This reduces the need to resend the entire search payload, such as the route, filters, or booker country. **How to use it:** 1. The first search request includes a `search_token` value in the response. 2. Include the `search_token` in subsequent requests to cars/availability, orders/preview and orders/create endpoints (from v3.2 Beta) instead of resending the full search criteria. search_token expiration The `search_token` expires after 90 minutes. ## When no data is returned If the search returns no cars: * Check that the pickup/dropoff location and datetime are valid and have available vehicles. * See the [Data conventions guide](/demand/docs/development-guide/code-conventions#dates-and-times) for right formats. * Review filters — overly strict transmission, mileage, or seat filters can exclude all results. * Verify that airport codes or city IDs are supported. * Find the full lists in the [/common location endpoints](/demand/docs/open-api/demand-api/commonlocations). If you still receive empty results, try broadening the search criteria or temporarily removing filters. ## Best practices | Best practice | Description | | --- | --- | | ✅ Optimise for performance | * Limit `maximum_results` to 20–50 for faster responses. * Use pagination tokens instead of fetching all results at once. | | ✅ Deliver relevant results | * Combine geographic (airport, coordinates, city) and qualitative (transmission, mileage, car categories) filters. * Use `sort.by` according to traveller needs (for example, price for value, distance for convenience). | | ✅ Maintain consistency | * Always include `currency` and `booker.country`. * Store location IDs from [/common location endpoints](/demand/docs/open-api/demand-api/commonlocations) to reduce API load. | Curious to know more? - [Car search use cases](/demand/docs/cars/search-cars-examples) for search examples. - [Car details](/demand/docs/cars/retrieve-car-details) for static data. - [Filtering and sorting guide](/demand/docs/cars/cars-filter-sorting) for best practices. - [Pagination guide](/demand/docs/development-guide/pagination) for instructions on handling large datasets.