Generic deeplink params structure and validation logic

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.

📘

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

👍

3 ways to pass user pickup or dropoff addresses in a deeplink

  1. Plain display address (via pickup and dropoff parameters).
  2. KPOI (pickup-kpoi and dropoff-kpoi parameters). Learn about what is KPOI [here]
  3. Google Place ids (pickup-place_id and dropoff-place_id parameters)
  4. Latitude/longitude coords (pickup-lat/lng and dropoff-lat/lng parameters)

NAME

Example VALUE

Format

pickup

20 Rue Jean Rey, 75015 Paris, France

string

pickup-kpoi

FRMPL

string

pickup-lat

51.509865

string

pickup-lng

-0.118092

string

pickup-place_id

ChIJrTLr-GyuEmsRBf

string

NAME

Example VALUE

Format

pickup-time

YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

DateTime

dropoff

Mohrenstrasse 37
10117 Berlin

string

dropoff-kpoi

MPH

string

dropoff-place_id

ChIJrTLr-GyuEmsRBf

string

dropoff-lat

51.509865

string

dropoff-lng

-0.118092

string

booking-type

ASAP
PRE-BOOK

string

🚧

It is mandatory to pass either a pick-up or a drop-off address in the form of an address, kpoi, place_id or lat/long in order to have a valid deeplink

It is also mandatory to pass either a pickup-time (for pre-book) or booking-type as ASAP for the deeplink to work

Metadata and custom parameters

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

pickup
dropoff

flight

FL1001

string

train

14553

string

passengers

3

number

train-time

13:40

string

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

NAME

Example VALUE

Format

passengers

3

number

first-name

Jon

string

last-name

Black

string

email

[email protected]

string

phone-number

+4437524342

string

luggage

1

number

meta.key1

value1

string

meta.key2

value2

string

traveller-locale

fr-FR

xx-XX string

booking-type

ASAP

ASAP or PRE-BOOK string

📘

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.

Other parameters

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

To be able to offer to a user a good end to end experience a deeplink must contain all parameters in the correct format. Otherwise, a user would be redirected to an empty form with ability to enter his booking details manually.

The validation rules vary based on a page you integrate to. A list of required parameters with examples can be find on corresponding pages: Deeplink to landing page, Deeplink to trip create page, Deeplink to quotes page.