Cars Search API

Retrieve rental car results

Overview

This API provides rental car search functionality. Initiate a search and retrieve results by repeatedly calling the /poll endpoint. The search progresses through two phases: a "first-phase" for quick results, and a "second-phase" for results from slower providers. Continue polling until the status field in the response indicates "complete."

Agencies

The API provides information on various agency types (opaque, peer-to-peer, and delivery), each with unique characteristics that affect the user experience. To better inform users, consider highlighting these differences:

Opaque Agencies: The agency name is hidden until booking confirmation.
Peer-to-Peer Agencies: The exact pickup location may be revealed only after booking.
Delivery Agencies: The car is delivered directly to the user's specified location.

Displaying result cards

The API returns data organized by agency, car, and location. Within each group, a list of potential booking options is provided, each identified by a provider code. Consumers can choose the first booking option from the list or implement custom logic to select a different option for displaying the result card.

Enums

API enum values may change in the future. Applications must be designed to handle both new and removed enum values without breaking application logic in such cases.

Usage

Start search by sending POST /i/api/affiliate/search/car/v1/poll?apiKey={apiKey}&userTrackId={userTrackId} request with search parameters.

Request examples

Example 1: Starting a round-trip search using KAYAK city id

POST /i/api/affiliate/search/car/v1/poll?apiKey={apiKey}&userTrackId={userTrackId}
{
  "searchStartParameters": {
    "pickup": {
      "location": {
        "type": "city",
        "value": "25588"
      },
      "date": "2025-04-24",
      "hour": 14,
      "minute": 30
    },
    "dropoff": {
      "date": "2025-04-28",
      "hour": 14,
      "minute": 30
    }
  }
}

Example 2: Starting one way search using airport

POST /i/api/affiliate/search/car/v1/poll?apiKey={apiKey}&userTrackId={userTrackId}
{
  "searchStartParameters": {
    "pickup": {
      "location": {
        "type": "airport",
        "value": "JFK"
      },
      "date": "2025-04-24"
    },
    "dropoff": {
      "date": "2025-04-28"
    }
  }
}

The response will contain a searchId and cluster response fields that must be used to continuously poll until the response comes back with a status of "complete".

Request example

POST /i/api/affiliate/search/car/v1/poll?apiKey={apiKey}&userTrackId={userTrackId}&cluster={cluster}
{
  "searchId": "QSBGBspPnD"
}

Resources:

/poll

Starts a new car search, or returns results for an existing search.

POST

/i/api/affiliate/search/car/v1/poll?apiKey=<string>&userTrackId=<string>&cluster=<string>

Request body

Body:

searchStart

{
    "searchStartParameters": {
        "pickup": {
            "location": {
                "type": "airport",
                "value": "BOS"
            },
            "date": "2025-03-01",
            "hour": 12,
            "minute": 30
        },
        "dropoff": {
            "date": "2025-03-02",
            "hour": 12,
            "minute": 30
        }
    }
}

searchPoll

{
    "searchId": "QSBGBspPnD"
}

Responses
200 - application/json
400 - application/json \| Bad request.
401 - application/json Authorization errors.
403 - application/json Request is not allowed.
429 - application/json Rate limit exceeded.

Response:

{
    "searchId": "JTAmAp5JvC",
    "cluster": "4",
    "status": "complete",
    "results": [
        {
            "id": "f6e29ded279a166d25dda122c0efbf3f",
            "bookingOptions": [
                {
                    "providerCode": "IPRICELINECAR",
                    "agencyCode": "hertz",
                    "bookingUrl": "https://sandbox-en-us.kayakaffiliates.com/in?url=/book/car?code=JXAmCRO-O3.Tzrmt2YKlNc-Vl3ODhcgCCwUw9Xn_JpDBHZ_T1_vMYU.7023.d6bd3983c5ec8c5b797d9fa1deb6fb94&h=9c953dc74471",
                    "pickupLocationId": "28634",
                    "policy": {
                        "cancellation": {
                            "isUnlimited": true
                        },
                        "mileage": {
                            "code": "limited",
                            "limit": 100,
                            "displayName": "100 mi"
                        },
                        "fuel": {
                            "code": "fullToFull",
                            "displayName": "full-to-full",
                            "description": "Pick up and drop off the car with a full tank"
                        },
                        "insurance": [
                            {
                                "code": "collision",
                                "limit": {
                                    "price": 1000,
                                    "displayPrice": "$1000"
                                },
                                "isWithDeductible": true,
                                "deductible": {
                                    "price": 11,
                                    "displayPrice": "$11"
                                }
                            },
                            {
                                "code": "theft",
                                "limit": {
                                    "price": 1000,
                                    "displayPrice": "$1000"
                                },
                                "isWithDeductible": true
                            }
                        ]
                    },
                    "car": {
                        "image": "https://content.r9cdn.net/carimages/generic/02_economy_red.png",
                        "type": {
                            "code": "economy",
                            "displayName": "Economy",
                            "groups": [
                                "small"
                            ]
                        },
                        "brand": "Fiat",
                        "sipp": "XFDA",
                        "fuel": "hybrid",
                        "bags": 2,
                        "passengers": 5,
                        "doors": "doors4"
                    },
                    "price": {
                        "price": 42,
                        "displayPrice": "$42"
                    },
                    "paymentType": "prepay",
                    "rateType": "bestAvailable",
                    "badges": [
                        {
                            "code": "freeCancellation",
                            "displayName": "Free Cancellation"
                        },
                        {
                            "code": "greatDeal",
                            "displayName": "Great Deal"
                        }
                    ]
                }
            ]
        },
        {
            "id": "a089ccec3b3dd639cab8602be25dfc18",
            "bookingOptions": [
                {
                    "providerCode": "IAIRPORTRENTALCARS",
                    "agencyCode": "hertz",
                    "bookingUrl": "https://sandbox-en-us.kayakaffiliates.com/in?url=/book/car?code=JXAmCRO-O3.vxvuh3q6vuOdimzhWNcJnbaYAeeTFjgE.7023.d6bd3983c5ec8c5b797d9fa1deb6fb94&h=d3641ced0a26",
                    "pickupLocationId": "28634",
                    "policy": {
                        "cancellation": {
                            "isUnlimited": true
                        }
                    },
                    "car": {
                        "image": "https://content.r9cdn.net/car-images/generic/02_economy_coolgrey.png",
                        "type": {
                            "code": "compact",
                            "displayName": "Compact",
                            "groups": [
                                "small"
                            ]
                        },
                        "brand": "Nissan Versa",
                        "features": [
                            {
                                "code": "ac",
                                "displayName": "Air conditioning"
                            }
                        ],
                        "bags": 2,
                        "passengers": 5,
                        "fuel": "diesel",
                        "sipp": "CDAR"
                    }
                },
                {
                    "providerCode": "IHOTWIRECARCORE",
                    "agencyCode": "hertz",
                    "bookingUrl": "https://sandbox-en-us.kayakaffiliates.com/in?url=/book/car?code=JXAmCRO-O3.vxvuh3q6vuOdimzhWNcJnbaYAeeTFjgE.7023.d6bd3983c5ec8c5b797d9fa1deb6fb94&h=d3641ced0a26",
                    "pickupLocationId": "28634",
                    "policy": {
                        "cancellation": {
                            "isUnlimited": false,
                            "limitHours": 24
                        }
                    },
                    "car": {
                        "image": "https://content.r9cdn.net/car-images/generic/02_economy_coolgrey.png",
                        "type": {
                            "code": "compact",
                            "displayName": "Compact",
                            "groups": [
                                "small"
                            ]
                        },
                        "brand": "Nissan Versa",
                        "fuel": "electric",
                        "transmission": "manual",
                        "sipp": "CDAR",
                        "bags": 1,
                        "passengers": 3
                    },
                    "paymentType": "prepay"
                }
            ]
        }
    ],
    "agencies": {
        "hertz": {
            "code": "hertz",
            "displayName": "Hertz",
            "logoUrls": {
                "horizontalUrl": "https://content.r9cdn.net/rimg/provider-logos/cars/h/hertz.png"
            },
            "type": "regular"
        }
    },
    "providers": {
        "IPRICELINE": {
            "code": "IPRICELINECAR",
            "displayName": "PricelineCar",
            "logoUrls": {
                "horizontalUrl": "https://content.r9cdn.net/rimg/provider-logos/cars/h/kayak-logo.png?crop=true&height=60&fallback=default2.png&_v=fc1d5a0afbf8662d8d6d68d01fa97633"
            }
        },
        "IAIRPORTRENTALCARS": {
            "code": "IAIRPORTRENTALCARS",
            "displayName": "AirportRentals",
            "logoUrls": {
                "horizontalUrl": "https://content.r9cdn.net/rimg/provider-logos/cars/h/kayak-logo.png?crop=true&height=60&fallback=default2.png&_v=fc1d5a0afbf8662d8d6d68d01fa97633"
            }
        },
        "IHOTWIRECARCORE": {
            "code": "IHOTWIRECARCORE",
            "displayName": "HotWireCar",
            "logoUrls": {
                "horizontalUrl": "https://content.r9cdn.net/rimg/provider-logos/cars/h/kayak-logo.png?crop=true&height=60&fallback=default2.png&_v=fc1d5a0afbf8662d8d6d68d01fa97633"
            }
        }
    },
    "carLocations": {
        "28634": {
            "locationId": "28634",
            "locationType": "shuttle",
            "coordinates": {
                "latitude": 42.36564733660332,
                "longitude": -71.00850028564457
            },
            "address": "15 Transportation Way",
            "cityName": "Boston",
            "countryCode": "US",
            "displayDistance": "1.1 mi",
            "airport": {
                "code": "BOS",
                "displayName": "Boston Logan Intl"
            }
        }
    },
    "pageSize": 500,
    "totalCount": 2,
    "currency": "USD",
    "priceMode": "total",
    "sort": {
        "key": "price"
    },
    "days": 2
}

Types:

SearchRequest

The request object sent to the car poll endpoint.

Properties
searchId	Search id for which to retrieve results. Set to `null` when starting a new search.
searchStartParameters	Optional parameters used to configure a new search. Not required when `searchId` is provided.
resultParameters	Optional parameters used to configure the results returned by a search.

SearchStartParameters

Properties
pickup Required	The location where the car will be collected.
dropoff Required	The location where the car will be returned.

SearchStartLocation

Search location.

Properties
type Required	The type of location.
value Required	The value of the location.

SearchStartLocationTypeenum

The type of location.

city: City id or free text of the city.
airport: IATA code of the airport.

city | airport

SearchStartLocationParameters

Search location parameters for pickup or dropoff.

Properties
location	The location where the car will be collected or returned. Must be present for pickup.
date Required	The date when the car will be collected or returned.
minute enum: 0 \| 30 Default: 0	The minute of the hour when the car will be collected or returned.
hour Default: 0	The hour when the car will be collected or returned.

SearchResultsParameters

Properties
priceMode Default: perDayTotal	The required pricing mode.
sort Default: {"key":"price"}	By which criteria results should be sorted.
pageNumber Default: 0	Page number of the results.
pageSize Default: 50	Results per page.
currency	Currency to which all prices are converted. Default is resolved by domain used.

SearchResponse

The response object returned by the car poll endpoint.

Properties
searchId Required	Unique identifier for the search.
cluster Required	Cluster to which poll requests should be made.
status Required	The current status of the search.
results Required	List of car search results.
sort Required Default: {"key":"price"}	Sort key by which results should be sorted in ascending order.
pageSize Required Default: 500	Result list page size.
totalCount Required	Total result count.
priceMode Required Default: perDayTotal	Price mode
agencies	Map containing `AgencyInfo` objects, with the agency `code` as keys and `AgencyInfo` object as values.
providers	Map containing `ProviderInfo` objects, with the provider `code` as keys and `ProviderInfo` object as values.
carLocations	Map containing `CarLocation` objects, with the `locationId` as keys and `CarLocation` object as values.
currency Required	Currency to which all prices are converted.
days Required	Number of days for the rental.

CarSearchResult

Car search result details.

Properties
id Required	Unique identifier for the result.
bookingOptions Required	List of available booking options for the car.

CarSearchResultBookingOption

Booking option specific information.

Properties
providerCode Required	The provider code. Provider can be looked up in `providers` root response field.
agencyCode Required	The code of the agency providing the service. Agency can be looked up in `agencies` root response field.
bookingUrl Required	Absolute url to book the car.
policy	Booking option policy details.
fees	ie. young or senior driver fee.
isCreditCardRequired	Does this provider require a credit card to book?
car	Details of the car this provider offers.
price	The car price this provider charges. Calculated based on the `priceMode` in the request.
pickupLocationId Required	Pick-up location id. A location id that can be looked up in `carLocations` root response field.
dropoffLocationId	Drop-off location id if car is not returned to original pick-up location. A location id that can be looked up in `carLocationMap` root response field..
paymentType enum: payAtPickup \| prepay \| deposit	Car payment type.
rateType enum: bestAvailable \| exclusive \| corporate	Car rate type.
badges	List of additional information about the car.

CarBookingOptionPolicy

Booking option policy details.

Properties
cancellation	Free cancellation policy.
mileage	Mileage policy.
fuel	Fuel policy.
insurance	List of car insurance policies.

AgencyInfo

Car rental agency providing the rental car service.

Properties
code Required	Agency code.
displayName Required	Agency display name.
logoUrls Required	Agency logo urls.
type Required enum: regular \| p2p \| opaque \| delivery \| includedDriver	Type of agency. regular: Regular car rental agency. p2p: Peer-to-peer car sharing agency. opaque: Opaque car rental agency. delivery: Car rental agency that delivers the car to the user. includedDriver: Car rental agencies that include a driver.

AgencyLogo

Agency logo urls.

Properties
horizontalUrl Required	Absolute horizontal agency's logo url.

ProviderInfo

Provider serving up the car rental information.

Properties
code Required	Provider code.
displayName Required	Provider display name.
logoUrls Required	Provider logo urls.

ProviderLogo

Provider logo urls.

Properties
horizontalUrl Required	Absolute provider's logo url.

CarLocation

Car rental agency location details.

Properties
locationId Required
coordinates	Car location geo point.
displayDistance Required	Distance from the search location.
airport	If this is an airport, this field will be populated with airport details.
address	Car location address.
locationType enum: inTerminal \| shuttle \| nonAirport \| checkForDetails \| callForPickup \| opaqueAirport	Car location type.
cityName	City name.
countryCode	Country code of the location.

CarAirportLocation

Airport location details.

Properties
code Required	Airport code.
displayName Required	Airport display name.
terminalName	The name of the terminal the agency is in.
countryName	Returned if the agency is in a different country from search destination.

CarCancellationPolicy

Cancellation policy details.

Properties
isUnlimited	Is cancellation unlimited?
limitHours	Number of hours before pickup when cancellation is allowed.
nonCancellationFee	Price of the non-cancellation fee.

CarMileagePolicy

Free mileage policy details.

Properties
code Required enum: limited \| unlimited
limit	Mileage limit if `limited`.
displayName	Localized mileage policy display name.

CarFuelPolicy

Localized fuel policy name & description.

Properties
code Required enum: fullToFull \| fullToEmpty \| halfToHalf \| halfToEmpty \| quarterToQuarter \| emptyToEmpty \| sameToSame	Fuel policy code.
displayName	Localized fuel policy name.
description	Localized fuel policy description.

CarInsurancePolicy

Single car insurance policy details.

Properties
code Required enum: collision \| theft \| thirdParty \| fire \| tireGlass	Type of insurance policy.
limit	Maximum coverage limit of the insurance policy.
isWithDeductible	Indicates if the insurance policy includes a deductible.
deductible	Amount of the deductible for the insurance policy.

CarFee

Details of additional fees associated with the car rental.

Properties
code Required enum: youngDriver \| seniorDriver \| dropOff \| afterHours \| deliveryFee \| securityDeposit	The type of fee.
rate	The rate of the fee.
isIncludedInTotal	Indicates if the fee rate is included in the total rental price (irrespective of whether the rate amount is known).

CarBadge

Properties
code Required enum: carSharing \| chauffeured \| greatDeal \| contactless \| delivery \| electric \| enhancedCleaning \| exclusive \| freeAdditionalDriver \| freeCancellation \| hybrid \| publicRate \| directBilling \| skipCounter \| earlyCheckin \| discount \| mobileRate	Badge code.
displayName Required	Localized badge display name.

CarTypeGroupenum

Set of car groups supported.

CarDetail

Properties
image	Absolute url of an image representing the car.
type Required	Car type details.
brand Required	The car brand.
bags Required	The number of bags the car can carry.
passengers Required	The number of passengers the car can carry.
doors enum: doors2 \| doors23 \| doors24 \| doors3 \| doors4 \| doors45 \| doors5 \| doors6 \| doors1	The number of doors the car has. doors2: 2 doors doors23: 2 or 3 doors doors24: 2 or 4 doors doors3: 3 doors doors4: 4 doors doors45: 4 or 5 doors doors5: 5 doors doors6: 6 doors doors1: 1 door
transmission enum: automatic \| manual	Car transmission type.
fuel enum: diesel \| petrol \| electric \| ethanol \| hybrid \| hydrogen \| lpgCompressed \| multiFuel	The fuel type of the car.
sipp	The car SIPP code.
features	List of short car features.

CarTypeDetail

Car type details.

Properties
code	Car type code.
displayName	The localized car type name.
groups	The set of car type groups that the car belongs to.

CarFeature

Car feature details

Properties
code Required	Feature code.
displayName Required	Localized feature display name.

CarFeatureCodeenum

Set of car features supported.

ac | navigationSystem

CarTypeenum

Set of car types supported. For types with special prefix car size is determined at pick-up.

Price

Price of something.

Properties
price Required
displayPrice Required	Formatted price, currency symbol included.

Geographic point

Properties
latitude Required
longitude Required

CurrencyCode

ISO 4217 code identifier for currency. Currency codes are composed of a country's two-character Internet country code plus a third character denoting the currency unit.

Pattern: [A-Z]{3}

Example:

USD

CountryCode

ISO 3166-1 alpha-2 code identifier for country. Country codes are composed of a country's two-character Internet country code.

Pattern: [A-Z]{2}

Example:

US

SippCode

Standardized code used to classify cars.

Pattern: ^[A-Z]{4}$

Example:

CCAR

AirportCode

An IATA (International Air Transport Association) code that identifies an airport (3 characters code).

Pattern: ^.{3}$

Example:

CPH

PriceModeenum

Defines the basis on which a price is calculated - total or per day cost, with or without taxes.

total | perDayTotal

SortCriteria

Sort request configuration.

Properties
key Required	By which criteria results should be sorted.

SortKeyenum

Sort key.

distance | price

SearchStatusCodeenum

The status field in the response indicates the current phase:

first-phase: The search is running and some initial results may be available. Clients should poll to retrieve more results.
second-phase: The results from most important providers are ready. Clients should display the results as if they were complete, and keep polling to retrieve more results.
complete: The list of results is final. Clients should stop polling

first-phase | second-phase | complete

SearchErrorResponse

Response returned when an error occurs, accompanied with a HTTP error code.

Properties
url Required	URL of failed request.
errors Required	List of errors.

Example:

{
    "url": "<<resourcePathName>>",
    "errors": [
        {
            "code": "ANONYMOUS_ACCESS_DENIED",
            "description": "anonymous access to kayak API denied.",
            "localizedDescription": "Anonymous access to kayak API denied."
        }
    ]
}

ErrorEntry

Representation of an error, includes an error code and error description.

Properties
code Required	Error code. Known error codes include: INTERNAL_ERROR: An internal error has occurred ...
description Required	Error message for debugging (not localized). This message is NOT intended to be shown to end users.
localizedDescription Required	Localized error message, for client consumption.

PreSearchErrorResponse

Error responses due to missed requirements (e.g, incorrect domain, missing headers).

Properties
status Required	Error status code.
errorCode Required	Error code.
errorMessage Required	Error description.

Example:

{
    "status": 401,
    "errorCode": "INVALID_API_KEY",
    "errorMessage": "Invalid API key: XXX"
}

Cookie preferences

Essential

Functional