Deeplinks
API Endpoint
www.kiwi.comImportant notice
This website does not contain documentation of the newest features.
If you are a new user of the Kiwi.com
APIs, we highly recommend using
tequila.kiwi.com.
To access Tequila documentation, create an account.
If you have any questions, use the Tequila support page.
This document describes the search deeplinks.
- method:
GET
search_deeplinks ¶
General specification
-
should run only within Affiliate Interface
-
possible to set all general deeplink parameters (as listed below)
-
will contain both required (mandatory) and optional parameters
-
will generate a deeplink
-
The responses are G-zipped and need to be unpacked (response header Content-Encoding: gzip).
Search_deeplink_structure - one way and return
Always start with www.kiwi.com/deep?
followed by parameters separated by the ‘&’ symbol.
Please note
-
Only active parameters have been described in this document. Parameters that are not described are deprecated.
-
All URLs must be encoded (for example use
%3B
instead of;
) -
Should you wish to highlight a specific flight after redirection create a normal search deeplink and add “id” from flights “data” object. The final deeplink will look like this - https://kiwi.com/deep?origin=STN&destination=PRG&departure=2019-05-01&affilid=lanthi#8877457203920450_0
Example:
Radius search
A great way to find the best deals is to search with a map radius. This way we can find even cheaper deals from airports that are not necessarily the closest but traveling there is still cheaper than flying from the closer airports.
To include several airports that are nearby, you need to use a map coordinate and a radius value.
The best way to determine these values is using our interactive map – in the destination form choose Radius Search
and set the search circle on the map as needed.
To use this search in the deeplink, input the given values in this format: from=49.72-15.73-250km
.
The radius value can be set as needed (up to 1000km) and needs to have the unit km
written with it. Radius search is available for both from=
and to=
parameters.
Handy tip: the easiest way to create a deeplink is to use kiwi.com front end - use the search section to specify the criteria you would like in the deeplink and copy the part of the URL that follows the nomad=
.
Search_deeplinks_generator ¶
Body
"Redirect to www.kiwi.com"
Headers
Content-Type: application/json
Body
{
"message": "Here you will be notified of the error that occurred."
}
Search_deeplinks_generatorGET/deep{?multicity,origin,destination,departure,return,multicity,affilid,lang,currency,passengers,market,SubIds}
What parameters to use when - When you use Multicity or Salesman parameters, do not use from
, to
, departure
and return
.
- affilid
string
(required) Example: testIDa unique partner ID (affilid). A text or number value given by our affiliate manager.
- lang
string
(optional) Example: eninterface language. International language code (en, cs, es, etc).
- currency
string
(optional) Example: gbpinterface currency. International currency code (czk, eur, usd, gbp, etc).
- passengers
integer
(optional) Example: 2number of passengers. A single number value.
adults=1&children=1&infants=1
can also be used to get more detailed information.- market
string
(optional) Example: dewill add a sub2 parameter to affilid e.g.
affilid=partner_de
. It should be a two letter ISO country code (de. au, ru)- SubIds
string
(optional) Example: IDSubIds
- origin
string
(required) Example: CZKiwi api ID of the departure location.
It accepts multiple values separated by comma, these values might be airport codes, city IDs, two letter country codes, metropolitan codes and radiuses as well as subdivision, region, autonomous_territory, continent and specials (Points of interest, such as Times Square).
Some locations have the same code for airport and metropolis (city), e.g. DUS stands for metro code Duesseldorf, Moenchengladbach and Weeze as well as Duesseldorf airport. See the following examples:
-
fly_from=city:DUS
will match all airports in “DUS”, “MGL” and “NRN” (all in the city of Duesseldorf) -
fly_from=DUS
will do the same as the above -
fly_from=airport:DUS
will only match airport “DUS” Radius needs to be in form lat-lon-xkm. The number of decimal places for radius is limited to 6. E.g.-23.24--47.86-500km
for places around Sao Paulo. ‘LON’ - checks every airport in London, ‘LHR’ - checks flights from London Heathrow, ‘UK’ - flights from the United Kingdom.Link to Locations API
. Previous name: from
-
- destination
string
(optional) Example: portoKiwi api ID of the arrival destination. It accepts the same values in the same format as the
origin
parameter. Previous name: to.If you don’t include any value you’ll get results for all airports in the world.
- departure
string
(optional) Example: 2016-12-20date of departure. A single date number value (2016-06-30) or a date range value (2016-06-30_2016-07-15). The format is expected in YYYY-MM-DD.
- return
string
(optional) Example: 2017-01-14date of return. A single date number value (2016-06-30) or a date range value (2016-06-30_2016-07-15). The format is expected in YYYY-MM-DD. Number of nights of stay can also be used - Only or a range of values (2-10, 4-7,…), for a single value use (5-5, 7-7,…).
no-return
is recommended to be used when there is no return date. This is preferred to leaving this parameter blank.- cabinClass
string
(optional) Example: premium-true‘true’ - only returns results belonging to the selected class; ‘false’ - means that mixed classes are applied (cabinClass=business-false).
Choices:
business-true
first-true
premium-true
business-false
first-false
premium-false
- transport
string
(optional) Example: aircraftthis parameter specifies the means of transport. For multiple values, please use
,
(comma) as a separator (aircraft,bus
). If no specification is specified, all transport options are returned.Choices:
bus
aircraft
train
- stopNumber
number
(optional) Example: 1this parameter is used to specify the maximum number of stops allowed. If left without specification, any number of stops will be included in the search results.
- flightDurationMax
number
(optional) Example: 38the maximum length of flight in hours
- stopDurationMax
number
(optional) Example: 12maximum length of the stopover duration in hours
- stopDurationMin
number
(optional) Example: 6minimum length of the stopover duration in hours
- times
string
(optional) Example: 4-16-5-18use this parameter to narrow down the departure and arrival times. The first set of two numbers
4-16
is for the departure. The second (5-18
) is the time range of arrival. Every other set of 2 integers means that the Apply for return check box is set. This is specified by underscore4-16-5-18_6-18-9-22
. (departure times of outbound flight - arrival times of outbound flight _ departure times of inbound flight - arrival times of inbound flight)- daysInWeek
string
(optional) Example: 012456-012456selected days writen in integers starting from 0 which stands for Sunday. Should the return box be selected, a dash
-
is used.- priceMax
number
(optional) Example: 841this parameter is used to specify the maximum price in EUR for the itinerary. Together with the
priceMin
a range is created and used.- priceMin
number
(optional) Example: 47this parameter is used to specify the minimum price in EUR for the itinerary. Together with the
priceMax
a range is created and used.- noBags
Boolean
(optional) Example: trueswitch for no bag itineraries. Use
false
to filter out flights that do not include bags.- airlinesList
string
(optional) Example: DU,MU,G9this parameter accepts airline IATA codes separated by comma and is used with the
selectedAirlinesExclude
parameter to either include or exclude these airlines in the search.- selectedAirlinesExclude
Boolean
(optional) Example: falseIf false is used, the airlines from the ‘airlineList’ are shown. If true is used, the airlines from the ‘airlineList’ are not included.
- airportsList
string
(optional) Example: LGWthis parameter accepts airport IATA codes separated by comma and is used with the
selectedStopoverAirportsExclude
parameter to either include or exclude these airports in the search.- selectedStopoverAirportsExclude
string
(optional) Example: trueIf false is used, the airports from the ‘airportsList’ are shown. If true is used, the airports from the ‘airportsList’ are not included.
- returnFromDifferentAirport
Boolean
(optional) Example: falseUse this parameter to allow a return from a different airport. ‘False’ = do not allow a return from a different airport. ‘True’ = do allow a return from a different airport.
- returnToDifferentAirport
Boolean
(optional) Example: falseUse this parameter to allow a return to a different airport. ‘False’ = do not allow a return to a different airport. ‘True’ = do allow a return to a different airport.
- overnightStopover
Boolean
(optional) Example: falseUse this parameter to allow overnight stopovers - stopover longer than 4 hours. ‘False’ = do not allow overnight stopovers. ‘True’ = do allow overnight stopovers.
- Nomad
string
(optional) Example: WRO~--~--;---~---~--;london_gb~-~--;new-york-city_ny_us~-~--;HKG~-~--;prague_cz~-~--The Nomad is also referred to as Salesman.
When you use Multicity or Nomad parameters, do not use
from
,to
,departure
andreturn
.The Nomad was created for those travelers, who would like to visit n-number of cities in any order. A time restriction is not mandatory. At the moment n = 10. It is fully functional in API. The
Nomad parameter
contains the values for destination, date_range and time_of_stay.Links always start with
www.kiwi.com/deep?nomad=
. The link contains the Nomad segment (the from / to / departure / return) and is followed by up to 10 via destinations. The Nomad segment is of formdestination~date_range~time_of_stay
. Individual segments are separated by;
and their order is: from;to;via1;via2;via3,via4,…, via10 -> example:JFK~2018-07-28_2018-08-03~--;LGA~2018-07-28_2018-08-03~--;PRG~--~3-9
which means that for those dates I want for fly from JFK, return to LGA and go via Prague and stay there for 3-9 days.brno_cz~2018-08-18~--%3Bsplit_hr~2018-12-21~--
is the format to use instead of specifying thefrom
.to
,departure
andreturn
.-
destination (optional, string, STN) … Destination of arrival (case sensitive! Must be capital letters). Either an international code of the airport (PRG, FCO, STN,…), a country code (GB, HR, IT,…), or a city with a country (LONDON_GB, PRAGUE_CZ, ROME_IT,…). If left blank, nothing defaults in.
-
date_range (optional, string, 2018-07-28 - 2018-09-03) … if left blank, the default value is today plus one month.
-
time_of_stay (optional, string, ‘4-8’) … if left blank, 3-5 days is used as default.
-
nomad_stopNumber (optional, number,
1
) … For Nomad only: This parameter is used to specify the number of stops. If left without specification, any number of stops will be returned in the search results. -
nomad_noBags (optional, Boolean,
true
) … For Nomad only: Use this parameter to include or exclude ‘no bag itineraries’. ‘True’ = include no bag itineraries. ‘False’ = do not include no bag itineraries.
-
- multicity
string
(optional) Example: vaclav-havel-airport-prague-prague-czechia~palma-de-mallorca-palma-spain~2018-07-03_2018-08-03;palma-de-mallorca-palma-spain~alicante-spain~2018-08-06_2018-08-09When you use Multicity or Salesman parameters, do not use
from
,to
,departure
andreturn
.-
origin (required, string,
CZ
) … Kiwi api ID of the departure location.It accepts multiple values separated by comma, these values might be airport codes, city IDs, two letter country codes, metropolitan codes and radiuses as well as subdivision, region, autonomous_territory, continent and specials (Points of interest, such as Times Square).
Some locations have the same code for airport and metropolis (city), e.g. DUS stands for metro code Duesseldorf, Moenchengladbach and Weeze as well as Duesseldorf airport. See the following examples:
fly_from=city:DUS
will match all airports in “DUS”, “MGL” and “NRN” (all in the city of Duesseldorf)fly_from=DUS
will do the same as the abovefly_from=airport:DUS
will only match airport “DUS” Radius needs to be in form lat-lon-xkm. The number of decimal places for radius is limited to 6. E.g.-23.24--47.86-500km
for places around Sao Paulo. ‘LON’ - checks every airport in London, ‘LHR’ - checks flights from London Heathrow, ‘UK’ - flights from the United Kingdom.Link to Locations API
. Previous name: from
-
multicity_noBags (optional, Boolean,
true
) … For Multicity only: Use this parameter to include or exclude ‘no bag itineraries’. ‘True’ = include no bag itineraries. ‘False’ = do not include no bag itineraries. -
multicity_transport (optional, string,
bus
) … this parameter specifies the means of transport. For multiple values, please use,
(comma) as a separator (aircraft,bus
). If no specification is specified, all transport options are returned.- Values
bus
aircraft
train
- Values
-
multicity_stopNumber (optional, number,
1
) … For Multicity only: This parameter is used to specify the number of stops. If left without specification, any number of stops will be returned in the search results. -
destination (optional, string,
porto
) … Kiwi api ID of the arrival destination. It accepts the same values in the same format as thefly_from
parameter. Previous name: to.If you don’t include any value you’ll get results for all airports in the world.
-
date_range (optional, string, 2018-07-28 - 2018-09-03) … if left blank, the default value is today plus one month.
-
Generated by aglio on 22 Feb 2022