Inline Ads API

Retrieve a list of Inline advertisements

General Usage

API usage is a 3 step process:

Request Inline Items
Trigger impressionUrl and trackUrl for any ads displayed
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 inline ads

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

POST

/i/api/ads/inline/v1/hotel/list

Request body
{ "checkinDate": "2020-08-26", "checkoutDate": "2020-08-29", "adults": 2, "rooms": 1, "cityId": "34713" }

Responses
200 - application/json Returns successful list of inline ads in the response { "inlineItems": [ { "rank": 1, "description": "Call Now and Save up to 40% off.", "site": "superfares.com", "logoUrl": "/kimg/logos/6ed6b5f0db11007d.png", "impressionUrl": "/s/impression/inline?providerCode=SuperFaresCTC_FIOAD_US&searchId=...", "headline": "Super savings only with Superfares.", "productType": "flight", "phoneNumber": "(855) 675-0648", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaqueAdBooking..", "bookingButtonText": "Call Us", "companyName": "SuperFares" }, { "rank": 2, "description": "Flights to 30+ European Cities", "site": "AerLingus.com", "logoUrl": "/kimg/logos/d3498ebe7dd7eea6.png", "impressionUrl": "/s/impression/inline?providerCode=AerLingusMinlineUS_FIOAD_US&searchId=...", "trackUrl": "/s/redirect/tracking?url=....", "headline": "Fly Aer Lingus Across Europe", "productType": "flight", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaque...", "bookingButtonText": "View Deal", "companyName": "Aer Lingus" } ] }
400 - application/json Common errors: `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 inline ads

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

POST

/i/api/ads/inline/v1/flight/list

Request body
{ "legs": [ { "originAirport": "BOS", "destinationAirport": "SFO", "date": "2020-08-29" }, { "originAirport": "SFO", "destinationAirport": "ORD", "date": "2020-09-06" } ], "passengers": [ "adult", "adult", "child" ] }

Request body

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

Responses
200 - application/json Returns successful list of inline ads in the response { "inlineItems": [ { "rank": 1, "description": "Call Now and Save up to 40% off.", "site": "superfares.com", "logoUrl": "/kimg/logos/6ed6b5f0db11007d.png", "impressionUrl": "/s/impression/inline?providerCode=SuperFaresCTC_FIOAD_US&searchId=...", "headline": "Super savings only with Superfares.", "productType": "flight", "phoneNumber": "(855) 675-0648", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaqueAdBooking..", "bookingButtonText": "Call Us", "companyName": "SuperFares" }, { "rank": 2, "description": "Flights to 30+ European Cities", "site": "AerLingus.com", "logoUrl": "/kimg/logos/d3498ebe7dd7eea6.png", "impressionUrl": "/s/impression/inline?providerCode=AerLingusMinlineUS_FIOAD_US&searchId=...", "trackUrl": "/s/redirect/tracking?url=....", "headline": "Fly Aer Lingus Across Europe", "productType": "flight", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaque...", "bookingButtonText": "View Deal", "companyName": "Aer Lingus" } ] }
400 - application/json Common errors: `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 inline ads

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

POST

/i/api/ads/inline/v1/car/list

Request body
{ "pickUpDate": "2020-08-29", "dropOffDate": "2020-09-01", "pickUpLocation": { "type": "city", "locationQuery": "34713" } }

Responses
200 - application/json Returns successful list of inline ads in the response { "inlineItems": [ { "rank": 1, "description": "Call Now and Save up to 40% off.", "site": "superfares.com", "logoUrl": "/kimg/logos/6ed6b5f0db11007d.png", "impressionUrl": "/s/impression/inline?providerCode=SuperFaresCTC_FIOAD_US&searchId=...", "headline": "Super savings only with Superfares.", "productType": "flight", "phoneNumber": "(855) 675-0648", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaqueAdBooking..", "bookingButtonText": "Call Us", "companyName": "SuperFares" }, { "rank": 2, "description": "Flights to 30+ European Cities", "site": "AerLingus.com", "logoUrl": "/kimg/logos/d3498ebe7dd7eea6.png", "impressionUrl": "/s/impression/inline?providerCode=AerLingusMinlineUS_FIOAD_US&searchId=...", "trackUrl": "/s/redirect/tracking?url=....", "headline": "Fly Aer Lingus Across Europe", "productType": "flight", "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaque...", "bookingButtonText": "View Deal", "companyName": "Aer Lingus" } ] }
400 - application/json Common errors: `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
403 - application/json Request is not allowed
404 - application/json Resource was not found
429 - application/json Rate limit exceeded

Types:

HotelInlineRequest

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

Properties
cityId Required	KAYAK city identifier
checkinDate Required	hotel search checkin date
checkoutDate Required	hotel search checkout date
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. Default size 154x58.
backgroundImageDimensions	requested dimensions of background image. Default size 750x200.
currencyCode	user's chosen ISO 4217 currency code. If nothing set, it will fallback to the domains default currency

Example:

{
    "checkinDate": "2020-08-26",
    "checkoutDate": "2020-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

FlightInlineRequest

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

Properties
legs Required	List of flight legs for the search context
cabin enum: economy \| premiumEconomy \| business \| mixed \| first Default: economy
passengers	list of all passengers part of the search context. Default to one adult passenger.
logoDimensions	requested dimensions of provider logo. Default size 154x58.
backgroundImageDimensions	requested dimensions of background image. Default size 750x200
currencyCode	user's chosen ISO 4217 currency code. If nothing set, it will fallback to the domains default currency

Example:

{
    "legs": [
        {
            "originAirport": "BOS",
            "destinationAirport": "SFO",
            "date": "2020-08-29"
        },
        {
            "originAirport": "SFO",
            "destinationAirport": "ORD",
            "date": "2020-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.

CarInlineRequest

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

Properties
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
logoDimensions	requested dimensions of provider logo. Default size 154x58.
backgroundImageDimensions	requested dimensions of background image. Default size 750x200.
currencyCode	user's chosen ISO 4217 currency code. If nothing set, it will fallback to the domains default currency

Example:

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

InlineItem

Properties
rank Required	the ad's position with respect to other ads in the response
site Required	the provider's site base URL or description to display as part of the ad
headline Required	text to display as the ad's headline
description Required	description to display under the ad's headline
bookingButtonText Required	text that should be displayed in the booking button
productType Required enum: car \| flight \| hotel	the ad's product type
logoUrl Required	logo url (Relative) for inline ad. Default size is 154x58.
impressionUrl Required	Impression URL that logs an Impression Event on the server. inline 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 inline ad items. Example: https://affiliate-en-us.kayakaffiliates.com/s/impression/cmp2?providerCode=CosmopolitanRRweb_US_HCMP2&productType=H&searchId=GrAkBvdhtN...
deepLink Required	Click out URL to provider from inline 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....
backgroundImageUrl	Background image URL to display in the ad's background.
phoneNumber	Phone number of the provider of the inline ad.
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/...
price	The cheapest price to display on the inline ad. If no price is available then this field will not be provided.
priceGroups	A price class and price for the given price class. Note that the price group will not be the same as the price field. It will be additional pricing options.
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.
companyName Required	The name of the company that paid for the ad.

PriceGroup

Properties
priceClass Required	A rating type. For flights this would be a mapping of non-stop (0) or one-stop (1) flights. For hotels this would be hotel stars, on a scale of 0 - 5. For cars this would be car class.
price Required	A price for the priceClass.

InlineResponse

Properties
inlineItems Required

Example:

{
    "inlineItems": [
        {
            "rank": 1,
            "description": "Call Now and Save up to 40% off.",
            "site": "superfares.com",
            "logoUrl": "/kimg/logos/6ed6b5f0db11007d.png",
            "impressionUrl": "/s/impression/inline?providerCode=SuperFaresCTC_FIOAD_US&searchId=...",
            "headline": "Super savings only with Superfares.",
            "productType": "flight",
            "phoneNumber": "(855) 675-0648",
            "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaqueAdBooking..",
            "bookingButtonText": "Call Us",
            "companyName": "SuperFares"
        },
        {
            "rank": 2,
            "description": "Flights to 30+ European Cities",
            "site": "AerLingus.com",
            "logoUrl": "/kimg/logos/d3498ebe7dd7eea6.png",
            "impressionUrl": "/s/impression/inline?providerCode=AerLingusMinlineUS_FIOAD_US&searchId=...",
            "trackUrl": "/s/redirect/tracking?url=....",
            "headline": "Fly Aer Lingus Across Europe",
            "productType": "flight",
            "deepLink": "/s/clickthrough.jsp?ctyp=InlineOpaque...",
            "bookingButtonText": "View Deal",
            "companyName": "Aer Lingus"
        }
    ]
}

ImageDimensions

An image's dimensions

Properties
height Required	image height
width Required	image width

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 €"
}

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.

Example:

DKK

GBP

USD

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 preferences

Essential

Functional