Integration via deep link

Through deep links, Travellers will be presented a set of relevant options allowing them to speed up the entry of what they want to purchase.

About a deep link

A deep link is a link that takes you to an entry point of a booking web application. It looks like a normal URL with a query string.

Karhoo deep link format is the following:

<host>/<path_to_landing_page>?<query-param-1>=<value>&<query-param-2>=<value>

📘

Note

Note: A deep link query params are case insensitive. Thus, <Query-Param-1> would be equal to <query-param-1>.

A deep link structure

Essential for a booking parameters

Pattern is leg-[N]-[NAME]=[VALUE] where

• leg a constant prefix for a leg number
• N is an positive integer representing a sequence of a journey leg
• NAME is any valid query parameter name
• VALUE is a value for a NAME property (URIEncoded string) and it should follow a format from a value specification table.

📘

Note

If VALUE doesn’t follow a correct format and a property is not required, the VALUE would fall back to a default value.

👍

Learn about what is KPOI here

📘

Note

Neither pickup nor pickup-kpoi nor pickup-place_id should be provided in order to have a valid deep link. All three are not accepted either. Same rules are applied to drop off parameters.

📘

Booking type

If booking-type is not specified for the journey leg then generic booking type will be used. See below for more information.

Metadata and Custom fields

Pattern is leg-[N]-M-[NAME]?-[META_NAME]=[VALUE] where

• leg a constant prefix for a leg number
• N is an positive integer representing a sequence of a journey leg
• “M-” a prefix denotes non standard field
• NAME - name of a parameter to which you want to apply meta. NAME can be omitted - then modification would be applied to both locations in a leg.
• META_NAME - a name for a property that you want to apply metadata for.

For example,

1. To add train information to pickup location leg-1-M-pickup-train can be specified
2. To add flight information to dropoff location leg-2-M-dropoff-flight can be specified
3. To override number of passengers per leg leg-1-M-passengers can be specified

Generic parameters

📘

How do we handle a traveller locale?

xx-XX it's any locale supported by a booking web application.

If it’s missing it will fall back:

1. to browser locale
2. to a default locale configured for a web app - If a browser locale is not supported either

📘

Booking type

If the booking type is not specified, then by default it will be considered PRE-BOOK.

For PRE-BOOK booking type pickup time is required.
For ASAP booking type pickup time should not be specified.

Generic booking type can be overwritten for each leg using 'leg-N-booking-type' query parameter.

👍

In addition to all params described above any custom parameters (e.g. utm_campaign or utm_source) can be added to a deep link.

Validation logic

A deep link would be valid if all parameters essential for a booking are provided in the correct format. Otherwise, a user would be redirected to an empty form with ability to enter his booking details manually.

In order to make a deep link valid, pickup or dropoff information should be provided to each leg as well as a time for a corresponding location.

For example,

FAQ

Q: Where to get place_id for a location?

A: We use Google Place IDs, find out more details how to get it here.

Examples

№1. From an address to an address with trip details prefilling

/landing?leg-1-pickup=Hilton%20London&leg-1-dropoff-place_id=ChIJhza7Doio2EcRSxpLpqDodAc&leg-1-pickup-time=2020-08-09T18%3A31%3A42-03%3A30&email=email%40of.user&luggage=2&passengers=3&first-name=first+name&last-name=last+name&phone-number=%2B441234567890&booking-type=PRE-BOOK

№2: From an address to X

/landing?leg-1-pickup=Mercure%20Paris%20Hotel&leg-1-pickup-time=2020-08-09T18:31:42-03:30&traveller-locale=en-GB&passengers=2&booking-type=PRE-BOOK

№3: From a train station KPOI to X

/landing?leg-1-pickup-kpoi=FRGD&leg-1-pickup-time=2020-08-09T18:31:42-03:30&passengers=2&booking-type=PRE-BOOK

№4: From X to a hotel and from a hotel to Y

/landing?leg-1-dropoff=Mercure%20Paris%20Hotel&leg-2-pickup=45+Rue+du+Dr+Babinski%2C+75018+Paris&leg-2-pickup-time=2020-08-09T18:31:42-03:30

№5: From X to Y with 2 passengers, 2 bags and train information

/landing?leg-1-pickup=Mercure%20Paris%20Hotel&leg-1-pickup-time=2020-08-09T18:31:42-03:30&leg-1-M-train=4312&leg-1-M-train-time=2020-08-09T17:31:42-03:30&leg-1-M-passengers=2&leg-1-M-luggage=2&leg-1-dropoff=45+Rue+du+Dr+Babinski%2C+75018+Paris&traveller-locale=en-GB&booking-type=PRE-BOOK