CompareTo Ads API

Retrieve a list of Compare To advertisements

Download RAML

General Usage

API usage is a 3 step process:

  1. Request CompareTo Items
  2. Trigger impressionUrl, trackUrl, trackUrl2 for any ads displayed
  3. Trigger deepLink for any ads clicked on

API calls will reject all API requests that contain unknown parameters, invalid parameters, empty parameters or parameters defined more than once. If a page has been idle for more than 5 hours, the request will need to be refreshed if the user comes back to the page.

API access control

All requests require apiKey and userTrackId request parameters.

In addition to the request parameters user's must pass in the appropriate user-agent and x-original-client-ip in the request header. Any incorrect usage of User-Agents could lead to inaccuracies in click and impression tracking, which may impact invoicing.

The response will also return a set of cookies including a cluster cookie (which data center the requests should be made to) that will need to be passed to all subsequent requests. This is necessary for us to be able to return and retrieve the appropriate information about the ads. Most http clients and all browsers should properly accept cookies set from the server in the response with the "Set-Cookie" header, so your next web service calls should simply work.

Resources:

Hotel compareTo ads

Get a list of ads to display in respect to hotel search context

POST
/i/api/ads/compareTo/v1/hotel/list
Request body
{
    "showOn": "results",
    "checkinDate": "2024-08-26",
    "checkoutDate": "2024-08-29",
    "adults": 2,
    "rooms": 1,
    "cityId": "34713"
}
Responses
200 - application/json

Returns successful list of compareTo ads in the response

{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "9933145",
            "name": "BookIt.com",
            "providerCode": "BookitHotelRR18_US_HCMP2",
            "rank": 1,
            "logoUrl": "/kimg/logos/768404d37e797dfb.png",
            "clickToCall": false,
            "precheck": "unselected",
            "productType": "hotel",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=BookitHotelRR18_US_HCMP2&productType=H&searchId=GWAkD6_cv9&pageOrigin=H&showOn=Results&rank=1&origin=&displayRail=R&destination=ctid:34713&numberOfDays=3&railsize=8&price=.00&_sid_=R-20oeQK75qmGNhx8am$OXF-XRFnh3wiWje2hKUALPcV_I3AWAbfTJArsHCAGqCNE",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=9933145&cpnid=7061234&ctyp=Search&ptyp=H&orig=H..RP..R0&octid=&pid=BookitHotelRR18_US_HCMP2&prv=BookitHotelRR18_US_HCMP2&srch=GWAkD6_cv9&ploc=US&lid=BookitHotelRR18_US_HCMP2-GWAkD6_cv9&c2c=&xp=unassigned&qadults=2&qrooms=1&qtravelers=2&qorig=&qdest=City:34713&qstart=1598414400000&qend=1598673600000&qshour=-1&qehour=-1&qow=false&qfcc=&qdctid=34713&qdac=&resid=&bookid=&stid=&qyouths=0&qchild=0&xpExt=&aidExt=&atype=cmp2&displayRail=R&h=&ah=TKKmYBwo8szjaVniSs9jfwfpGmYDudk$qntjBYGSw7s&pj=cLSAZd_63GVTkMYwnS3qBw==&_sid_=R-20oeQK75qmGNhx8am$OXF-XRFnh3wiWje2hKUALPcV_I3AWAbfTJArsHCAGqCNE&rank=1",
            "companyName": "BookIt.com"
        }
    ]
}
400 - application/json

VALIDATION_ERROR - at least one request field was invalid. Please review request and documentation UNRECOGNIZED_CITY - unknown pick up city, either city id was not provided or invalid city id INVALID_CHECKIN_DATE - invalid checkin date INVALID_CHECKOUT_DATE - invalid checkout date CHECKOUT_DATE_MUST_BE_AFTER_CHECKIN_DATE - checkout date must be after checkin date AT_LEAST_ONE_GUEST_PER_ROOM - at least one guest per room must be provided

403 - application/json

Request is not allowed

404 - application/json

Resource was not found

429 - application/json

Rate limit exceeded

Flight compareTo ads

Get a list of ads to display in respect to flight search context

POST
/i/api/ads/compareTo/v1/flight/list
Request body
{
    "showOn": "results",
    "legs": [
        {
            "originAirport": "BOS",
            "destinationAirport": "SFO",
            "date": "2024-08-29"
        },
        {
            "originAirport": "SFO",
            "destinationAirport": "ORD",
            "date": "2024-09-06"
        }
    ],
    "passengers": [
        "adult",
        "adult",
        "child"
    ]
}
Responses
200 - application/json

Returns successful list of compareTo ads in the response

{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "9947562",
            "name": "Alaska Airlines",
            "providerCode": "AlaskaCMHRR2020_US_FCMP2",
            "rank": 1,
            "logoUrl": "/kimg/logos/ae1385c4be559d81.png",
            "clickToCall": false,
            "precheck": "selected",
            "productType": "flight",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=AlaskaCMHRR2020_US_FCMP2&productType=F&searchId=GiAiAYcQZk&pageOrigin=F&showOn=Results&rank=1&origin=aid:BOS&displayRail=R&destination=aid:SFO&numberOfDays=8&railsize=&price=.00&_sid_=R-2JWMicE2A8L$N7Eio1nCn-K4TAps6c1YQ3Usquq0dzw461ccQG3fVSVKDQqbUus",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=9947562&cpnid=7056845&ctyp=Search&ptyp=F&orig=C..RP..R0&octid=&pid=AlaskaCMHRR2020_US_FCMP2&prv=AlaskaCMHRR2020_US_FCMP2&srch=GiAiAYcQZk&ploc=US&lid=AlaskaCMHRR2020_US_FCMP2-GiAiAYcQZk&c2c=&xp=unassigned&qadults=1&qrooms=0&qtravelers=1&qorig=Airport:BOS&qdest=Airport:SFO&qstart=1598673600000&qend=1599364800000&qshour=-1&qehour=-1&qow=false&qfcc=e&qdctid=13852&qdac=SFO&resid=&bookid=&stid=&qns=false&qnearby=3&qnearbyo=true&qnearbyd=true&qcages=&qinfantseat=0&qinfantlap=0&qsenior=0&qdac=SFO&qoac=BOS&qyouths=0&xpExt=&aidExt=&atype=cmp2&displayRail=R&h=&ah=DXK0R2wPUerAXiYyyktgvyJVfm7LwRTVAMiv3whsUts&pj=pQL5UuUXeDJoWkccbJKD8w==&_sid_=R-2JWMicE2A8L$N7Eio1nCn-K4TAps6c1YQ3Usquq0dzw461ccQG3fVSVKDQqbUus&rank=1",
            "companyName": "Alaska Airlines"
        }
    ]
}
400 - application/json

VALIDATION_ERROR - at least one request field was invalid. Please review request and documentation UNRECOGNIZED_AIRPORT - at least one search context airport could not be found INVALID_DEPARTURE_DATE - invalid departure date INVALID_RETURN_DATE - invalid return date

403 - application/json

Request is not allowed

404 - application/json

Resource was not found

429 - application/json

Rate limit exceeded

Car compareTo ads

Get a list of ads to display in respect to car search context

POST
/i/api/ads/compareTo/v1/car/list
Request body
{
    "showOn": "results",
    "pickUpDate": "2020-08-29",
    "dropOffDate": "2020-09-01",
    "pickUpLocation": {
        "type": "city",
        "locationQuery": "34713"
    }
}
Responses
200 - application/json

Returns successful list of compareTo ads in the response

{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "8620289",
            "name": "Hotwire",
            "providerCode": "HOTWIREFLOAT_US_CCMP2",
            "rank": 1,
            "logoUrl": "/kimg/compare2/logos/mobileX2/hotwire-Redlogo-154x58.png",
            "clickToCall": false,
            "precheck": "selected",
            "productType": "car",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=HOTWIREFLOAT_US_CCMP2&productType=C&searchId=GeAmCOUYh2&pageOrigin=C&showOn=Results&rank=1&date1=2020-08-29&origin=ctid:34713&displayRail=R&destination=ctid:34713&numberOfDays=3&date2=2020-09-01",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=8620289&cpnid=7060068&ctyp=Search&ptyp=C&orig=C..RP..R0&octid=34713&pid=HOTWIREFLOAT_US_CCMP2&prv=HOTWIREFLOAT_US_CCMP2&srch=GeAmCOUYh2&ploc=US&lid=HOTWIREFLOAT_US_CCMP2-GeAmCOUYh2&c2c=&xp=unassigned&qadults=&qrooms=0&qtravelers=0&qorig=City:34713&qdest=City:34713&qstart=1598673600000&qend=1598932800000&qshour=0&qehour=0&qow=false&qfcc=&qdctid=34713&qdac=&resid=&bookid=&stid=&xpExt=M3573&aidExt=&atype=cmp2&displayRail=R&h=&ah=dQWTCJ3W4nbhDkhsJdF_7KNCR4wDvCECXhe7cJDjlwg&pj=4RgVoRdZ3mc1mNkyEEK$8Q==&_sid_=R-2uClkBFwtnAU$7_AW25lB-UPIQOa7YQ2NlOnBYGvvp2Ic5_gwwImriSci3_PQVB&rank=1",
            "companyName": "Hotwire"
        }
    ]
}
400 - application/json

Common error codes:

  • VALIDATION_ERROR - at least one request field was invalid. Please review request and documentation
  • UNKNOWN_PICKUP_CITY - unknown pick up city, either city id was not provided or invalid city id
  • UNKNOWN_DROP_OFF_CITY - unknown drop off city, either city id was not provided or invalid city id
  • INVALID_PICKUP_DATE - invalid pick up date
  • INVALID_DROP_OFF_DATE - invalid drop off date
  • UNSUPPORTED_SHOWON_TYPE - the showOn type provided in the request, is not supported.
403 - application/json

Request is not allowed

404 - application/json

Resource was not found

429 - application/json

Rate limit exceeded

Types:

CompareToItem

CompareTo response. Contains all data for UI display

Properties
id

ad placement id used for ART testing

termId

search term id used for ART testing

name
Required

name of compareTo to display to user

providerCode
Required

code to be utilized for request to get cmp2s through kayak

rank
Required

compareTo position relative to other compareTos in the response

logoUrl
Required

logo url (Relative) for compareTo ad. Default size is 154x58.

clickToCall
Required

Click to call flag. True when compareTo phone number should be used instead of deepLink.

phoneNumber

compareTo ad phone number. This will be returned when clickToCall is true.

productType
Required
enum: car | flight | hotel

product type of compareTo ad.

impressionUrl
Required

Impression URL that logs an Impression Event on the server. compareTo ad url that should be fired when the ad is displayed on the UI. It should be displayed no more than 5 hours after the initial request retrieve compareTos.

Example:
https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=CosmopolitanRRweb_US_HCMP2&productType=H&searchId=GrAkBvdhtN&pageOrigin=H&showOn=Results&rank=1&date1=2020-08-26&origin=&destination=ctid:34713&numberOfDays=3&date2=2020-08-29
deepLink
Required

Click out URL to provider from compareTo ad. This logs a click event and redirects to provider's site.

Example:
https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=9947473&cpnid=7059874&ctyp=Search&ptyp=H&orig=H....&octid=&pid=CosmopolitanRRweb_US_HCMP2&prv=CosmopolitanRRweb_US_HCMP2&srch=GrAkBvdhtN&ploc=US&lid=CosmopolitanRRweb_US_HCMP2-GrAkBvdhtN&c2c=&xp=unassigned&qadults=2&qrooms=1&qtravelers=2&qorig=&qdest=City:34713&qstart=1598414400000&qend=1598673600000&qshour=-1&qehour=-1&qow=false&qfcc=&qdctid=34713&qdac=&resid=&bookid=&stid=&qyouths=0&qchild=0&xpExt=&aidExt=&atype=cmp2&displayRail=R&h=&ah=OUQK8fFXM7GZv1eQvN5RVJ9J_rmCZ8ZQZE2z8RFkeWU&pj=Hui8B9q0NbmYXEya0IEx6A==&_sid_=R-2vD$KZ3_yKNqrYLNQepPu-dYgC6aFlijSyRgMqg3EtppuvA3JxHEe3SmDegUAjD&rank=1
trackUrl

3rd Party Tracker URL for Providers (Fully Qualified). This should be called by the client when the ad is displayed, if available. It allows providers to use their own 3rd party tracking to keep track of when an Ad is shown.

Example:
https://www.kayak.com/s/redirect/...
trackUrl2

Secondary 3rd party tracking URL

Example:
https://www.kayak.com/s/redirect/...
cpcEstimate

An estimate of cost per click(cpc) for the ad. This value is based on the requesting affiliates revenue share. It is also just an estimate rounded to the nearest 10 cents. The data will only be available for some affiliates.

precheck
Required
enum: selected | unselected | unsupported

Indicates state of default UI selection. The ad can either be selected, unselected, or unsupported.

companyName
Required

Name of the company that paid for the ad.

ImageDimensions

An image's dimensions

Properties
height
Required

image height

width
Required

image width

CompareToResponse

Properties
searchId
Required

searchID to utilize when making a request to retrieve cmp2s through kayak

compareToItems
Required
Example:
{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "9933145",
            "name": "BookIt.com",
            "providerCode": "BookitHotelRR18_US_HCMP2",
            "rank": 1,
            "logoUrl": "/kimg/logos/768404d37e797dfb.png",
            "clickToCall": false,
            "precheck": "unselected",
            "productType": "hotel",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=BookitHotelRR18_US_HCMP2&productType=H&searchId=GWAkD6_cv9&pageOrigin=H&showOn=Results&rank=1&origin=&displayRail=R&destination=ctid:34713&numberOfDays=3&railsize=8&price=.00&_sid_=R-20oeQK75qmGNhx8am$OXF-XRFnh3wiWje2hKUALPcV_I3AWAbfTJArsHCAGqCNE",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=9933145&cpnid=7061234&ctyp=Search&ptyp=H&orig=H..RP..R0&octid=&pid=BookitHotelRR18_US_HCMP2&prv=BookitHotelRR18_US_HCMP2&srch=GWAkD6_cv9&ploc=US&lid=BookitHotelRR18_US_HCMP2-GWAkD6_cv9&c2c=&xp=unassigned&qadults=2&qrooms=1&qtravelers=2&qorig=&qdest=City:34713&qstart=1598414400000&qend=1598673600000&qshour=-1&qehour=-1&qow=false&qfcc=&qdctid=34713&qdac=&resid=&bookid=&stid=&qyouths=0&qchild=0&xpExt=&aidExt=&atype=cmp2&displayRail=R&h=&ah=TKKmYBwo8szjaVniSs9jfwfpGmYDudk$qntjBYGSw7s&pj=cLSAZd_63GVTkMYwnS3qBw==&_sid_=R-20oeQK75qmGNhx8am$OXF-XRFnh3wiWje2hKUALPcV_I3AWAbfTJArsHCAGqCNE&rank=1",
            "companyName": "BookIt.com"
        }
    ]
}
{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "9947562",
            "name": "Alaska Airlines",
            "providerCode": "AlaskaCMHRR2020_US_FCMP2",
            "rank": 1,
            "logoUrl": "/kimg/logos/ae1385c4be559d81.png",
            "clickToCall": false,
            "precheck": "selected",
            "productType": "flight",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=AlaskaCMHRR2020_US_FCMP2&productType=F&searchId=GiAiAYcQZk&pageOrigin=F&showOn=Results&rank=1&origin=aid:BOS&displayRail=R&destination=aid:SFO&numberOfDays=8&railsize=&price=.00&_sid_=R-2JWMicE2A8L$N7Eio1nCn-K4TAps6c1YQ3Usquq0dzw461ccQG3fVSVKDQqbUus",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=9947562&cpnid=7056845&ctyp=Search&ptyp=F&orig=C..RP..R0&octid=&pid=AlaskaCMHRR2020_US_FCMP2&prv=AlaskaCMHRR2020_US_FCMP2&srch=GiAiAYcQZk&ploc=US&lid=AlaskaCMHRR2020_US_FCMP2-GiAiAYcQZk&c2c=&xp=unassigned&qadults=1&qrooms=0&qtravelers=1&qorig=Airport:BOS&qdest=Airport:SFO&qstart=1598673600000&qend=1599364800000&qshour=-1&qehour=-1&qow=false&qfcc=e&qdctid=13852&qdac=SFO&resid=&bookid=&stid=&qns=false&qnearby=3&qnearbyo=true&qnearbyd=true&qcages=&qinfantseat=0&qinfantlap=0&qsenior=0&qdac=SFO&qoac=BOS&qyouths=0&xpExt=&aidExt=&atype=cmp2&displayRail=R&h=&ah=DXK0R2wPUerAXiYyyktgvyJVfm7LwRTVAMiv3whsUts&pj=pQL5UuUXeDJoWkccbJKD8w==&_sid_=R-2JWMicE2A8L$N7Eio1nCn-K4TAps6c1YQ3Usquq0dzw461ccQG3fVSVKDQqbUus&rank=1",
            "companyName": "Alaska Airlines"
        }
    ]
}
{
    "searchId": "searchId",
    "compareToItems": [
        {
            "id": "8620289",
            "name": "Hotwire",
            "providerCode": "HOTWIREFLOAT_US_CCMP2",
            "rank": 1,
            "logoUrl": "/kimg/compare2/logos/mobileX2/hotwire-Redlogo-154x58.png",
            "clickToCall": false,
            "precheck": "selected",
            "productType": "car",
            "impressionUrl": "https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=HOTWIREFLOAT_US_CCMP2&productType=C&searchId=GeAmCOUYh2&pageOrigin=C&showOn=Results&rank=1&date1=2020-08-29&origin=ctid:34713&displayRail=R&destination=ctid:34713&numberOfDays=3&date2=2020-09-01",
            "deepLink": "https://affiliate-en-us.kayakaffiliates.com/s/clickthrough.jsp?plid=8620289&cpnid=7060068&ctyp=Search&ptyp=C&orig=C..RP..R0&octid=34713&pid=HOTWIREFLOAT_US_CCMP2&prv=HOTWIREFLOAT_US_CCMP2&srch=GeAmCOUYh2&ploc=US&lid=HOTWIREFLOAT_US_CCMP2-GeAmCOUYh2&c2c=&xp=unassigned&qadults=&qrooms=0&qtravelers=0&qorig=City:34713&qdest=City:34713&qstart=1598673600000&qend=1598932800000&qshour=0&qehour=0&qow=false&qfcc=&qdctid=34713&qdac=&resid=&bookid=&stid=&xpExt=M3573&aidExt=&atype=cmp2&displayRail=R&h=&ah=dQWTCJ3W4nbhDkhsJdF_7KNCR4wDvCECXhe7cJDjlwg&pj=4RgVoRdZ3mc1mNkyEEK$8Q==&_sid_=R-2uClkBFwtnAU$7_AW25lB-UPIQOa7YQ2NlOnBYGvvp2Ic5_gwwImriSci3_PQVB&rank=1",
            "companyName": "Hotwire"
        }
    ]
}

HotelCompareToRequest

Request data including search fields needed in order to compareTo ads relevant for a hotel search

Properties
showOn
Required
cityId
Required

KAYAK city identifier

checkinDate
Required

hotel search checkin date

checkoutDate
Required

hotel search checkout date

requireIFrameSupport
Default: false

If true, only compareTo ads that support HTML iFrames will be returned. If false, compareTo ads may or may not support iFrames.

adults
Default: 2

hotel search, number of adults

rooms
Default: 1

hotel search, number of rooms

children
Default: 0

hotel search, number of children

logoDimensions

requested dimensions of provider logo

Example:
{
    "showOn": "results",
    "checkinDate": "2024-08-26",
    "checkoutDate": "2024-08-29",
    "adults": 2,
    "rooms": 1,
    "cityId": "34713"
}

FlightLeg

CompareTo flight leg

Properties
originAirport
Required

origin airport IATA code

destinationAirport
Required

destination airport IATA code

date
Required

flight leg departure date

FlightCompareToRequest

Request data including search fields needed in order to compareTo ads relevant for a flight search

Properties
showOn
Required
legs
Required

List of flight legs for the search context

cabin
enum: economy | premiumEconomy | business | mixed | first
Default: economy
passengers
Default: adult

List of all passengers part of the search context.

requireIFrameSupport
Default: false

If true, only compareTo ads that support HTML iFrames will be returned. If false, compareTo ads may or may not support iFrames.

logoDimensions

requested dimensions of provider logo

Example:
{
    "showOn": "results",
    "legs": [
        {
            "originAirport": "BOS",
            "destinationAirport": "SFO",
            "date": "2024-08-29"
        },
        {
            "originAirport": "SFO",
            "destinationAirport": "ORD",
            "date": "2024-09-06"
        }
    ],
    "passengers": [
        "adult",
        "adult",
        "child"
    ]
}

CarLocation

Car location types and identifier for the location type

Properties
type
Required
enum: city | airport

car search location type

locationQuery
Required

If type is city, this should be the KAYAK city identifier. If the type is airport this should be an airport IATA code.

CarCompareToRequest

Request data including search fields needed in order to compareTo ads relevant for a car search

Properties
showOn
Required
pickUpLocation
Required

car search pick up location.

dropOffLocation

car search drop off location. If location not provided, it will default to same as pick up location.

pickUpHour

car search pick up hour. Default is noon, 12. Available options are 0-23.

dropOffHour

car search drop off hour. Default is noon, 12. Available options are 0-23.

pickUpDate
Required

car search pickup date

dropOffDate
Required

car search drop off date

requireIFrameSupport
Default: false

If true, only compareTo ads that support HTML iFrames will be returned. If false, compareTo ads may or may not support iFrames.

logoDimensions

requested dimensions of provider logo

Example:
{
    "showOn": "results",
    "pickUpDate": "2020-08-29",
    "dropOffDate": "2020-09-01",
    "pickUpLocation": {
        "type": "city",
        "locationQuery": "34713"
    }
}

ShowOnenum

Location placement is shown.

frontDoor | results | searchAgain | panel | modal

Passengerenum

adult | senior | youth | child | lapInfant | seatInfant | student

Price

Price of something in some currency.

Properties
price
Required
currency
Required
Pattern: [A-Z]{3}

Currency code

localizedPrice
Required

Formatted price, currency symbol included

Example:
{
    "price": 1234,
    "currency": "EUR",
    "localizedPrice": "1.234 €"
}

ErrorResponse

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."
        }
    ]
}

Error

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
localizedDescription

Localized error message, for client consumption

Cookie SettingsCookie PolicyPrivacy Policy

The KAYAK Affiliate Network lets you link from any brand you likeEnhance and monetize your travel content with flights, hotels, cars and more!

KAYAK logo
HotelsCombined logo
Momondo logo
Cheapflights logo

©2026 KAYAK Affiliate Network

Cookie preferences