Integration via deep link
Deep link is a method of passing the user’s required information from the Demand Partner’s side to a Karhoo web booking application
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.
| NAME | Example VALUE | Format | Required |
|---|---|---|---|
| pickup | 20 Rue Jean Rey, 75015 Paris, France | String | * |
| pickup-kpoi | FRMPL | String | * |
| pickup-place_id | ChIJrTLr-GyuEmsRBf | String | * |
Learn about what is KPOI here
| NAME | Example VALUE | Format | Required |
|---|---|---|---|
| pickup-time | YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) | DateTime | yes |
| dropoff | Mohrenstrasse 37 10117 Berlin | String | * |
| dropoff-kpoi | MPH | String | * |
| dropoff-place_id | ChIJrTLr-GyuEmsRBf | String | * |
| booking-type | ASAP | ASAP or PRE-BOOK | no |
Note
Neither
pickupnorpickup-kpoinorpickup-place_idshould 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-typeis 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.
| NAME | META_NAME | Example VALUE | Format | Required |
|---|---|---|---|---|
| pickup dropoff | flight | FL1001 | String | No |
| train | 14553 | String | No | |
| passengers | 3 | Positive Integer | No | |
| train-time | 13:40 | String | No |
For example,
- To add train information to pickup location
leg-1-M-pickup-traincan be specified - To add flight information to dropoff location
leg-2-M-dropoff-flightcan be specified - To override number of passengers per leg
leg-1-M-passengerscan be specified
Generic parameters
| NAME | Example VALUE | Format | Required |
|---|---|---|---|
| passengers | 3 | Positive Integer | No |
| first-name | Jon | String | No |
| last-name | Black | String | No |
| [email protected] | String | No | |
| phone-number | +4437524342 | E.164 | No |
| luggage | 1 | Positive Integer | No |
| meta.key1 | value1 | String | No |
| meta.key2 | value2 | String | No |
| traveller-locale | fr-FR | xx-XX | No |
| booking-type | ASAP | ASAP or PRE-BOOK | No |
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:
- to browser locale
- 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,
| Parameters provided | Valid |
|---|---|
| leg-1-pickup, leg-1-pickup-time, booking-type=PRE-BOOK | yes |
| leg-1-pickup-kpoi, leg-1-pickup-time | yes by default booking type is PRE-BOOK |
| leg-1-pickup-kpoi, booking-type=ASAP | yes |
| leg-1-pickup-kpoi, leg-1-booking-type=ASAP, booking-type=PRE-BOOK | yes generic booking type is PRE-BOOK but it is overwritten by leg-1-booking-type |
| leg-1-pickup-place_id, leg-1-pickup-time | yes |
| leg-1-pickup-place_id, leg-1-pickup-time, leg-1-booking-type=PRE-BOOK | yes |
| leg-1-dropoff, leg-2-pickup, leg-2-pickup-time | yes |
| leg-1-dropoff, leg-2-pickup-time | no leg-2-pickup should be provided |
| leg-1-dropoff, leg-2-pickup, leg-2-pickup-time, booking-type=ASAP | no booking type is ASAP but pickup time is specified |
| leg-1-dropoff, leg-2-pickup, booking-type=PRE-BOOK | no leg-2-pickup-time should be provided |
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
№2: From an address to X
№3: From a train station KPOI to X
№4: From X to a hotel and from a hotel to Y
№5: From X to Y with 2 passengers, 2 bags and train information
Updated over 4 years ago