Partner Link Specifications

This document discusses the concept of Google vacation packages partner links, allowing Google to forward travelers directly into itineraries on a partner booking website. The target audience for this document is:

  • Partner business analysts or managers interested in interfacing their booking engine with vacation packages
  • Engineers and architects looking to understand the API and GH integration

Our goal is to provide a great experience for the user - this means:

  1. a reliable interface, that
  2. takes them to the specific package they want, with
  3. the minimum number of steps.

Once a user finds the package they want on Google, we want to direct them to a booking page with a predefined package. Google supports a variety of links to your website. The Partner Link API uses Google's standard API to direct a user to an itinerary on your website. This is the quickest way to get up and running. A deep link can accomplish the same result, but requires custom integration effort, as explained in the following sections.

Terminology

Google vacation, or holiday, packages
A service that assists users in locating a hotel plus flights packaged together for a given price, and connecting those users to an online destination where they can book their selected package.
Link

A URL that can be called via GET or POST with a set of parameters, resulting in an itinerary, or set of flights and hotel. These results are then presented to the user from your website. A link can be one of:

  1. Partner Link API: A preconfigured link hosted on your site that adheres to our API, allowing for seamless links into your website. This is a standardized deep link with the advantages of being much faster to integrate and more stable to change, since it's compatible with our standard API.

  2. Deep link: A link to a predefined itinerary that matches the parameters the user selected in a Google travel search. The landing page for a deep link should be pre-populated and ready to book.

Which to use?

Partner Link API (Best) Deep Link (Good)
Supported API that integrates with an itinerary on your site. Fastest and most reliable option for travel package integration. Custom integration that links to an itinerary on your site.

Linking your booking site with Google packages

Users spend time searching through a number of travel options hoping to find a great package. Our goal is not only to help them find great packages, but to simplify the booking process once they've decided what they want.

Our preferred option is for a partner to support the Partner Link API. This interface defines a standard GET API between Google vacation packages and the partner's website with a predefined set of parameters outlined in Partner Link API parameters. When a user selects one or more flights and is ready to book, that information is encoded into this standard URL format which is then sent to the partner's site.

By implementing the Partner Link API, a partner will be able to quickly integrate with Google's standard packages feature. Not only are Partner Link interfaces expedited due to the simpler integration, but they are also more robust since a standard, controlled interface is applied between Google and the partner.

The Partner Link API is covered in Partner Link API.

If a partner is unable to implement the standard interface for a Partner Link API, the alternative is to integrate via a deep link, taking a user directly from search results to their selected itinerary on the partner's booking web site. This is a better experience than forwarding them to search results, since they have already told us what trip itinerary they want.

A deep link should lead to a "review your booking" style of page that shows a single itinerary and price, and allows a user to immediately transition to booking the package.

We are able to provide external partner services with the following user-selected information when constructing the deep link. We may provide some or all of this information, depending on the features supported by the partner's interface.

  • Flight numbers
  • Flight dates and times
  • Origin and destination airport (for each segment)
  • Number/type of passengers
  • Booking code
  • Cabin class
  • Displayed price
  • Property ID of the hotel in the package
  • Check-in date
  • Length of stay at the hotel

The Partner Link API allows a partner to implement a standard URL interface in their system that can accept an itinerary booking request from Google. This request contains all the information required to describe an itinerary and generate a booking page.

The main blocks of information in an itinerary request are:

  • ItineraryRequest: The container for all the information needed to define an itinerary
    • TripDetails: The details about the overall journey
    • Passengers: Instructions on the numbers/types of passengers
    • Segment1: Information about the first segment of a flight
    • Segment2: Information about the second segment of a flight
    • Slices: Describes the major stages of a trip, e.g., the portions of a user-requested, multi-city itinerary. One slice can consist of one or more segments.

Our API applies the following convention for leg, segment, and slice terminology to ensure consistency between GH and your implementation:

Leg
The movement of an aircraft from one departure airport to the next station in the trip.
Segment
Consists of one or more consecutive legs, provided that the carrier and flight number have not changed.
Slice
Consists of one or more segments, conveying the travel intent of the customer. Each slice represents a portion of a trip with an origin and destination that the customer intends to visit, including technical stops or brief connections along the way.

Example

If a customer books a trip departing from CITY_A with a planned stopover in CITY_B, then leaves several hours later to fly to CITY_C, that represents two legs, two segments, and two slices. This is different from a trip where the customer wants to fly from CITY_A to CITY_C, requiring a brief layover and plane change in CITY_B - a trip with two segments but a single slice. The slice parameters can be ignored if this concept is not supported by your site.

Itinerary parameters

The Itinerary Request parameters are described below:

  • Passengers
    • Adult (integer, optional) - Number of adults (ages 18+) to be booked with this itinerary.
  • TripDetails
    • PointOfSaleCountry (string, mandatory) - ISO country code for point of sale. This represents their home country, and must adhere to ISO 3166 2-character codes. Example: CA.
    • UserCurrency (string, mandatory) - ISO currency code for the individual booking the package, representing their home currency. This must adhere to the 3-character alphabetical ISO 4217 codes. Example: USD.
    • DisplayedPrice (double, mandatory) - This is the displayed price as determined by Google at time of itinerary selection. Example: 173.42.
    • DisplayedPriceCurrency (string, mandatory) - This is the displayed price currency as determined by GH at time of itinerary selection. It adheres to the same format as TripDetails:Currency. Example: USD.
    • UserLanguage (string, mandatory) - ISO language code for the individual booking the flight, representing their home country's primary language, or a personalized selection if available. This must adhere to the 2-character ISO 639-1:2002 standard. Example: EN.
    • ReferralId (string, optional) - This is an optional string identifier that can provide cues to the partner regarding the Itinerary Request source. Example: GOOG_GH_712.
  • Slices
    • Slice1 (string, optional) - A string of the format 1,2,3 or 4,5 that groups segments by segment index, where the first segment index is 1. The slice should only point to segment indices corresponding to the specified Segments (see below). Slice1, the first slice, represents the outbound part of the trip.
    • Slice2 (string, optional) - The slice representing the inbound portion of the trip.
  • Segment (Repeating section)
    • Cabin (string, mandatory) - For each segment, specify the cabin. If multi-cabin support is not available, the same cabin will be repeated for all segments. One of: Economy, PremiumEconomy, Business, First. We currently support only Economy cabins.
    • Carrier (string, mandatory) - IATA code for the carrier responsible for that flight segment.
    • DepartureDate (string, mandatory) - Specifies the date of departure for the time zone of the departure station. This date format must adhere to ISO 8601, i.e., YYYY-MM-DD. Example: 2019-12-31 represents Dec. 31st, 2019.
    • Origin (string, mandatory) - IATA airport station code for the originating airport of this segment.
    • Destination (string, mandatory) - IATA airport station code for the destination airport for this segment. For a multi-segment trip, each segment will have different destination codes.
    • BookingCode (string, optional) - Single-character code representing the fare type for the flight.
    • FlightNumber (integer, mandatory) - Numeric flight number (excluding the airline 2-alpha code) for that segment.
  • Hotel
    • PropertyId (string, mandatory) - Identifier for the specific property the user wants to book. This must match one of the identifiers supplied by the partner in the hotel feed shared with Google at the beginning of the integration.
    • ArrivalDate (string, mandatory) - Specifies the arrival date at the given property (e.g., check-in date). This date format must adhere to ISO 8601, i.e., YYYY-MM-DD. Example: 2019-12-31 represents Dec. 31st, 2019.
    • LengthOfStay (integer, mandatory) - Specifies the number of nights to spend at the given property.

This information will be pushed to the partner booking site in real-time once a user has selected a package and indicated that they want to book. Our system will assemble the above information and submit it in one of two ways:

  1. GET: information is sent to a URL, specified by Partner:BaseURL + a query string as a GET request. The encoding of this URL is discussed in the following section.
  2. POST: parameters will be POST-ed to Partner:BaseURL using the same parameters specified for the GET HTTP request.

Submitting requests

The GET method will construct a URL + query string that resembles the form:

$BASE_URL + "?paramA=valueA&paramB=valueB&...

Repeating items will be enumerated as: paramA1, paramA2, paramA3. For example, if slices are included in the Itinerary Request, they will be labeled as:

...&Slice1=1,2,3&Slice2=4,5&Slice3=6&...

For repeating blocks, namely the Segment set, all parameters will be enumerated with a trailing number to represent the segment ID. For simplicity, all attributes within a Segment will be uniquely named so that they do not conflict with other attributes within the request. As an example, segment #3 in the itinerary could look like:

...&Destination3=ORD&FlightNumber3=123&Origin3=BOS&...

This URL will be sent as a GET request, unencrypted, and encoded/escaped to be W3C-compliant. Refer to Appendix B for sample URLs.

The POST method sends the same parameters in an HTTP POST request of type application/x-www-form-urlencoded. The keys in the key-value pair are the same as the parameters used by the GET method.

Authentication

GET and POST requests are not encrypted, and we do not support authentication mechanisms between GH and the partner site.

We do support HTTPS, and encourage its use on the partner site. Our assumption is that any protection of the landing page is managed by the partner website's security measures, just as they would protect any other pages on their site.

If the partner wishes to whitelist access to GH servers, IP ranges will be supplied and can be used to configure the partner's firewalls.

Appendix A: Partner configuration details

The following information will be provided by partners:

  • AccountPOCEmail (mandatory, string) - The email address for an account/management point of contact. This should be a fully qualified email format, e.g., user@domain.com.

  • AccountPOCName (mandatory, string) - The name of the individual designated as the account manager point of contact.

  • BaseURL (mandatory, string) - The base URL that will be receiving Itinerary Requests from GH. It should be of the form: https://_domain._name.com[:port]/full/path/to/service.

  • CallCenterPhone (mandatory, string) - The call center phone number to be referenced when a deep link cannot be properly generated and/or a user chooses to contact the call center directly to book or ask questions. This is an alphanumeric string, so extensions, hyphens and parentheses are supported. Text comments should not be appended to this value.

  • PartnerName (repeating, mandatory, string) - The full partner name to be displayed along with deep links. Can be repeated, and of the form EN=partner_name to support localization of the brand in different countries.

  • HigherCabinSupport (mandatory, boolean) - True/False to indicate if higher cabins can be specified in the deep link. We may choose to send this parameter anyways, allowing your service to upgrade cabin support in the future.

  • MultiSliceSupport (mandatory, boolean) - True/False to indicate if the partner's booking system understands and can accept slices. If true, optional Slice instructions will be provided in the itinerary request.

  • OtherItineraryRestrictions(optional, string) - A free text field that partners can use to document other restrictions (such as device types, user countries, currencies, and so on) that may need to be considered in the partner integration.

  • PassengerTypeMap (mandatory, string) - Case-insensitive string using IATA passenger codes. Because partners use different age ranges, this is mandatory and should be of the form INF=0-1,CHD=2-11,ADT=12-200. Age ranges are in integer years, and include all days within the year, e.g., 0-1 applies to an infant between the age of 0 and 1 year + 364 days.

  • ReferralId (optional, string) - Optional string to be embedded in itinerary requests to specify the source of the request. This referral ID will be passed by GH for all itinerary requests represented in alpha-numeric format. Example: GOOG_GFH_712.

  • RequestType (mandatory, string) - One of "get", or "post". This specifies how the partner will receive itinerary requests, e.g. as a URL + query string, or a POST-ed set of key/value pairs.

  • SiteURL (repeating, mandatory, string) - The site URL that points to the main website for the partner, e.g., http://www.partnerXYZ.com. This should always point to the top-level URL for the website's primary web presence. This field can also be supplied as EN=www.url1.com/path/to/en/page/ where EN is the ISO language code. This item can be specified multiple times as a repeating element.

  • TechPOCEmail (mandatory, string) - The technical point of contact email, e.g., user@domain.com.

  • TechPOCName (mandatory, string) - The individual designated as the technical point of contact.

Appendix B: sample URLs

Multi-segment, no slices, single passenger:

http://www.example.com/path/to/service?Adult=1&PointOfSaleCountry=US& \
UserCurrency=USD&DisplayedPrice=764.01&DisplayedPriceCurrency=USD& \
UserLanguage=EN&ReferralId=GOOG_GFH_712&Cabin1=Economy&Carrier1=AA& \
DepartureDate1=2019-03-01&Origin1=BOS&Destination1=LAX&BookingCode1=Y& \
FlightNumber1=123&PropertyId=42&CheckinDate=2019-03-01&LengthOfStay=7

Extracted parameters:

In this case, the optional empty parameters are sent.

Adult: 1, Child: 0, Infant: 0, InfantLap: 0
PointOfSaleCountry: US, UserCurrency: USD, UserLanguage: EN
Price: 764.01 USD
Referral ID: GOOG_GFH_712

Segment #1: Origin=BOS, BookingCode=Y, Destination=LAX, FlightNumber=123,
Carrier=AA, DepartureDate=2019-03-01, id=1, Cabin=Economy
Segment #1: Origin=LAX, BookingCode=Y, Destination=BOS, FlightNumber=321,
Carrier=BB, DepartureDate=2019-03-08, id=1, Cabin=Economy

Hotel: PropertyId=42, CheckinDate=2019-03-01, LengthOfStay=7

Multi-segment, two slice, multiple passengers:

http://www.example.com/path/to/service?Adult=2&Child=0&Infant=1&InfantLap=0& \
PointOfSaleCountry=US&UserCurrency=USD&DisplayedPrice=1090.05& \
DisplayedPriceCurrency=USD&UserLanguage=EN&ReferralId=GOOG_GFH_712& \
TripType=RoundTrip&Slice1=1,2&Slice2=3&Cabin1=Economy&Carrier1=DL& \
DepartureDate1=2019-03-01&Origin1=ZRH&Destination1=LHR&BookingCode1=F& \
FlightNumber1=315&Cabin2=Business&Carrier2=AA&DepartureDate2=2019-03-02& \
Origin2=LHR&Destination2=ORD&BookingCode2=J&FlightNumber2=306&Cabin3=First& \
Carrier3=AC&DepartureDate3=2019-03-03&Origin3=ORD&Destination3=ZRH& \
BookingCode3=J&FlightNumber3=792&PropertyId=42&CheckinDate=2019-03-02& \
LengthOfStay=7

Extracted parameters:

In this case the optional empty params are not sent - equally valid.

Adult: 2,
PointOfSaleCountry: US, UserCurrency: USD, UserLanguage: EN
Price: 1090.05 USD
Referral ID: GOOG_GFH_712
Slice 1: [1, 2]
Slice 2: [3]

Segment #1: Origin=ZRH, BookingCode=F, Destination=LHR, FlightNumber=315,
Carrier=DL, DepartureDate=2019-03-01, id=1, Cabin=Economy
Segment #2: Origin=LHR, BookingCode=J, Destination=ORD, FlightNumber=306,
Carrier=AA, DepartureDate=2019-03-02, id=2, Cabin=Business
Segment #3: Origin=ORD, BookingCode=J, Destination=ZRH, FlightNumber=792,
Carrier=AC, DepartureDate=2019-03-09, id=3, Cabin=First

Hotel: PropertyId=42, CheckinDate=2019-03-02, LengthOfStay=7