Building Dynamic URLs

Hotel listings include links to landing pages where the end-users can book rooms. You can define how Google constructs the link so that it includes additional information about the user and their itinerary. For example, you can include information such as the hotel ID, language and currency codes, and check-in dates in the URL.

Overview

You define the landing page URL in the Point of Sale file.

When the ad is displayed, dynamic information in the URL is replaced with actual values. To add dynamic values to your POS URLs, use the following syntax:

<URL>http://partner_url?param_id=(variable_name)</URL>

The following example shows a URL that uses Google's variable names in place of the actual values for the hotel ID and itinerary:

<URL>http://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)
  &amp;checkinDay=(CHECKINDAY)&amp;checkinMonth=(CHECKINMONTH)
  &amp;checkinYear=(CHECKINYEAR)&amp;nights=(LENGTH)</URL>

When the POS link is constructed for the search results page, Google replaces the variable names (or placeholders) with the actual values so that the URL includes the dynamic information. For example, if the user books a room for 6 nights starting on 6/7/2016 for hotel #42, Google renders the previous link as the following:

http://www.partnerdomain.com?hotelID=42&checkinDay=07&checkinMonth=06&checkinYear=2016&nights=6

Values that Google assigns to the variables in the query string depend on the corresponding data in your Hotel Price Feed and Hotel List Feed, as well as user-specific settings. For example, the value of the LENGTH variable is assigned the value of the <Nights> element from the related itinerary's price feed. The value of the PARTNER-HOTEL-ID variable is defined by the <id> element in the Hotel List Feed for the hotel that matched the user's search criteria.

Some variables are subsets of the price feed elements. For example, the CHECKINDAY, CHECKINMONTH, and CHECKINYEAR variables are extracted from the single <Checkin> element in the price feed. Other variables are calculated based on the user's locale and other client settings.

For more information about the sources of variable values, see Hotel Price Feed and Hotel List Feed XML Syntax.

URL variables

The following table describes the available variables that you can use to construct your POS URL:

Variable Description
ADVANCE‑BOOKING‑WINDOW The number of days in advance of the checkin date (in the hotel's timezone) that the booking took place. For example, "36".
CHECKINDAY The two-digit day defined in the <Checkin> element of the Hotel Price Feed. For example, "20".
CHECKINDAY-OF-WEEK The day of the week ("0" = Monday, "6" = Sunday) on which the check-in takes place, in the hotel's timezone. For example, "1" (Tuesday).
CHECKINMONTH The two-digit month defined in the <Checkin> element of the Hotel Price Feed. For example, "06".
CHECKINYEAR The four-digit year defined in the <Checkin> element of the Hotel Price Feed. For example, "2017".
CHECKOUTDAY The two-digit day calculated from the <Nights> and <Checkin> elements of the Hotel Price Feed. For example, "23".
CHECKOUTMONTH The two-digit month calculated from the <Nights> and <Checkin> elements of the Hotel Price Feed. For example, "07".
CHECKOUTYEAR The four-digit year calculated from the <Nights> and <Checkin> elements of the Hotel Price Feed. For example, "2017".
CLICK-TYPE Indicates whether the user clicked on an ad for a hotel or for a Room Bundle. Possible values are:
  • "hotel": The user clicked on an ad for a hotel.
  • "room": The user clicked on an ad for a Room Bundle.
CLOSE-RATE-RULE-IDS A comma-separated list of rate rule IDs for rates that were unavailable, but which could have been available if the user had taken a minor action. Note that rate rule IDs for qualified rates will always be populated here when a corresponding UI treatment is shown to the end user.
CUSTOM[1-5] The values of the custom fields that are defined in a Transaction message's <Result> element. For more information, see Overview of Transaction Messages.
DATE-TYPE Indicates whether the user selected the default date or specified a date when searching. Possible values are:
  • "default": The user clicked on a hotel ad where the default dates were used.
  • "selected": The user clicked on a hotel ad with the dates set.

GOOGLE-SITE The Google property on which a user viewed your hotel-pricing data. Possible values are:
  • "localuniversal": The user found the ad through organic search, typically by searching on google.com.
  • "mapresults": The user found the ad through maps.google.com.
  • "placepage": The user found the ad through plus.google.com/local.
  • "verification": Google uses this value when performing data quality tests on your site. You are not billed for these queries. Google Analytics can use this parameter and its value for identifyng Hotel Ads verification traffic.
  • "unknown": The user found the ad through an undetermined source.
LENGTH The length of stay in terms of the number of nights defined by the <Nights> element in the Hotel Price Feed. For example, "3".
NUM-ADULTS The occupancy for the Room Bundle. The default value is "2", which applies to base rates and Room Bundles without an occupancy definition. This parameter is highly recommended if you are using Room Bundles.
PACKAGE-ID The unique package ID for a Room Bundle. Matches the <PackageID> in the <RoomBundle> block.
PARTNER-CURRENCY The three-letter currency code defined by the <Baserate> element's currency attribute in the Hotel Price Feed. For example, "USD" or "CAD".
PARTNER-HOTEL-ID The unique identifier for the hotel defined by the <id> element in the Hotel List Feed.
PARTNER-ROOM-ID The unique identifier for the room in the Hotel Price Feed. For a standard room, the room ID is the value of the <RoomID> element within a <Result> block. For a Room Bundle, the room ID is the value of the <RoomID> element within the <RoomBundle> or <RoomData> blocks of the Transaction message.
PAYMENT-ID Resolves to a pre-defined string “commission”, or Google’s assigned IATA number (for example, "01234567") if you use a commissions collection agency. To change the formatting of your IATA number or pre-defined string, contact your Technical Account Manager (TAM).
PRICE-DISPLAYED-TAX The amount of tax displayed to the user in the user's local currency. The value of PRICE-DISPLAYED-TAX is the value of the <Tax> element in the Hotel Price Feed. For example, "3.14".
PRICE‑DISPLAYED‑TOTAL The total cost of the room that is displayed to the user in the user's local currency. The value of PRICE-DISPLAYED-TOTAL is the sum total of the <Baserate>, <Tax>, and <OtherFees> elements from the Hotel Price Feed. For example, "152.13".
RATE-PLAN-ID The ID as defined by the <RatePlanID> element in a price feed's <RoomBundle> block. For more information, see Room Bundles.
RATE-RULE-ID The ID as defined by the rate_rule_id attribute within a price feed's <Rate> block. For more information, see Fenced Rates.
USER-COUNTRY Two-letter country code indicating the location of the user. This information is extracted from the end-user's client settings. For example, "US" or "FR".
USER-CURRENCY Three-letter currency code indicating the user's local currency. The value of the USER-CURRENCY variable is inferred from the end-user's client settings. For example, "USD" or "CAD".
USER-DEVICE The end-user's device type. The value of USER-DEVICE can be one of the following:
  • "mobile"
  • "tablet"
  • "desktop"
  • "unknown"

The value of the USER-DEVICE variable is inferred from the end-user's client settings.

USER-LANGUAGE The two-letter language code that specifies the display language of the ad. The value of the USER-LANGUAGE variable is inferred from the end-user's client settings. For example, "en" or "fr".
VERIFICATION A boolean that verifies if the link was generated by Google. "true" if the link was generated by Google. Otherwise, "false".

In addition to the variables listed above, you can also use special directives to create conditional logic during the URL construction. These directives include:

  • ELSE
  • ENDIF
  • IF-CLICK-TYPE-HOTEL
  • IF-CLICK-TYPE-ROOM
  • IF-CLOSE-RATE-RULE-IDS
  • IF-DEFAULT-DATE
  • IF-PAYMENT-ID
  • IF-RATE-RULE-ID

For more information, see Using conditional logic in URLs.

General rules when building URLs

All variables are optional. You are not required to insert any variables in your POS URL. However, using variables to pass itinerary- and user-specific information generally creates a better experience for the end-user and aids you in conforming to Google's policies.

The following general rules apply when defining constructed URLs in a Points of Sale file:

  • All variables are surrounded with open and close parentheses.
  • Query string parameters can only be passed after the question mark ("?") in the URL.
  • Query string parameters must be separated by an ampersand ("&") in the final output. Because the ampersand is a special character in XML (and the Points of Sale file format is XML), you must use the encoded entity "&amp;" in its place. The final output renders an actual "&" character. For example:
    <!-- Do this: -->
    <URL>http://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&amp;nights=(LENGTH)</URL>
    
    <!-- Do NOT do this: -->
    <URL>http://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&nights=(LENGTH)</URL>

    You must also URL-encode special characters that you might include in the POS URL; for example:

    • space (" "): Replace space characters with "%20;" in the <URL> element
    • forward slash ("/"): Replace forward slashes with "%2F;" in the <URL> element

    Not all non-alphabetical characters must be URL encoded. For example, hyphens ("-") do not need to be URL encoded. For a list of common characters that must be URL encoded, see URL Encoding Table.

  • Values for a single parameter can be constructed from multiple variables. The following example constructs a single parameter, checkinDate, from the CHECKINDAY, CHECKINMONTH, and CHECKINYEAR variables:
    <URL>http://www.partnerdomain.com?checkinDate=(CHECKINDAY)%2F;(CHECKINMONTH)%2F;(CHECKINYEAR)</URL>

    This example results in a URL that might look like the following:

    http://www.partnerdomain.com?checkinDate=7/23/1971
  • You can use any ID for the name of the query string parameters. Your server processes these values. However, the values that you pass are limited to the list of available variables.
  • You can use up to five custom variables in addition to the list of available variables.

Using conditional logic in URLs

You can use special directives in the <URL> element of a Points of Sale file to conditionally build endpoints.

The conditional logic supports the following directives:

  • if_statement: If true, then the values that follow this condition are inserted into the URL. Otherwise, the values following the ELSE directive are inserted.

    Possible statements are:

    • IF-CLICK-TYPE-HOTEL: Resolves to true if the user clicked on an ad for a hotel; otherwise resolves to false.
    • IF-CLICK-TYPE-ROOM: Resolves to true if the user clicked on an ad for a Room Bundle; otherwise resolves to false.
    • IF-CLOSE-RATE-RULE-IDS: Resolves to true if one or more fenced rates were unavailable because the user did not take a minor action. Otherwise, resolves to false. Will always be true if a qualified rate UI treatment was shown to the end user.
    • IF-DEFAULT-DATE: Resolves to true if the user clicked on a hotel ad where default dates were used; otherwise resolves to false.
    • IF-PAYMENT-ID: Resolves to true for hotels in the Commissions program; otherwise false.
    • IF-RATE-RULE-ID: Resolves to true if the user selected a fenced rate; otherwise resolves to false.
  • ELSE: If the previous condition is not met, then the values that follow this condition are inserted into the URL.
  • ENDIF: Ends the conditional block.

IF-CLICK-TYPE-HOTEL example

You can construct a conditional block that checks if the user selected a Hotel without an explicit Room Bundle (the value of the <RatePlanID> element in the <Room Bundle> block of a Transaction message will be set to the implicitly associated room bundle to the price the user selected).

The following example uses this directive in a Points of Sale file:

<URL>http://partner.com/(IF-CLICK-TYPE-HOTEL)landing(ELSE)landing_room(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>

In this example, if the end-user selected a Room Bundle, the result is the following URL:

http://partner.com/landing_room?hid=123

If the end-user did not select a Room Bundle, the result is the following URL:

http://partner.com/landing?hid=123

IF-CLICK-TYPE-ROOM example

You can construct a conditional block that checks if the user selected a Room Bundle.

The following example uses this directive in a Points of Sale file:

<URL>http://partner.com/(IF-CLICK-TYPE-ROOM)landing_room(ELSE)landing(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>

In this example, if the end-user did not select a Room Bundle, the result is the following URL:

http://partner.com/landing?hid=123

If the end-user selected a Room Bundle, the result is the following URL:

http://partner.com/landing_room?hid=123

IF-DEFAULT-DATE example

Use the IF-DEFAULT-DATE conditional statement to set a non-date parameter that your website can then use to trigger custom behavior if the user did not select a date.

The following example checks if the default date was used:

<URL>http://partner.com?hotelID=(PARTNER-HOTEL-ID)
&amp;checkinDay=(CHECKINDAY)&amp;checkinMonth=(CHECKINMONTH)&amp;checkinYear=(CHECKINYEAR)
&amp;nights=(LENGTH)(IF-DEFAULT-DATE)&amp;popup_datepicker=true(ELSE)
&amp;popup_datepicker=false(ENDIF)</URL>

In this example, if the end-user did not select a date, the result might be similar to the following URL (showing default date selections):

http://partner.com?hotelID=123&checkinDay=01&checkinMonth=07&checkinYear=2017&nights=1&popup_datepicker=true

If the end-user selected a date, the result might be similar to the following URL, depending on the itinerary they selected:

http://partner.com?hotelID=123&checkinDay=23&checkinMonth=07&checkinYear=2017&nights=2&popup_datepicker=false

IF-PAYMENT-ID example

Use the IF-PAYMENT-ID conditional statement to vary the URL based on whether the click is a result of the Commissions program or not. The example below checks to see if a click came from the Commissions program and assigns a value to the booking_source parameter based upon the result:

<URL>http://partner.com?hid=(PARTNER-HOTEL-ID)&booking_source=(IF-PAYMENT-ID)(PAYMENT-ID)(ELSE)cpc(ENDIF)</URL>

If the hotel is part of the Commissions program, the result is one of the following URLs:

  • If no IATA number has been assigned to Google:
    http://partner.com?hid=123&booking_source=commissions
  • If an IATA number has been assigned to Google:
    http://partner.com?hid=123&booking_source=01234567

Otherwise, the result is the following URL:

http://partner.com?hid=123&booking_source=cpc

IF-RATE-RULE-ID example

You can construct a conditional block that checks if the user selected a fenced rate (and therefore the value of the <RateRuleID> element in the <Rate> block of a Transaction message is used).

The following example uses this directive in a Points of Sale file:

<URL>http://partner.com?hid=(PARTNER-HOTEL-ID)(IF-RATE-RULE-ID)&amp;customerType=42(ELSE)(ENDIF)</URL>

In this example, if the end-user did not select a fenced rate, the result is the following URL:

http://www.partner.com?hid=123

If the end-user selected a fenced rate, the result is the following URL:

http://www.partner.com?hid=123&customerType=42