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 landing pages file.
When the ad is displayed, dynamic information in the URL is replaced with actual values. To add dynamic values to your landing page URLs, use the following syntax:
<URL>https://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>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID) &checkinDay=(CHECKINDAY)&checkinMonth=(CHECKINMONTH) &checkinYear=(CHECKINYEAR)&nights=(LENGTH)</URL>
When the landing page 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:
https://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, refer to Hotel Price Feed and Hotel List.
URL variables
The following table describes the available variables that you can use to construct your landing page URL:
Variable | Recommended/optional | Description |
---|---|---|
ADVANCE‑BOOKING‑WINDOW |
Optional | The number of days in advance of the checkin date (in the hotel's timezone) that the booking took place. For example, "36". |
ALTERNATE-HOTEL-ID |
Recommended (if you have separate IDs to identify properties versus booking engines) | An alternate identifier for your property. This variable is specified in your Hotel List Feed. Having separate IDs is useful if you might need one property identifier for your feed information and another property identifier for your booking engine. |
CAMPAIGN-ID |
Recommended (applies only to Ads) | (Hotel Ads only) The ID of the Google Ads campaign you'd like to associate with the URL. This will be blank if a legacy non-campaign bid won the auction. |
CHECKINDAY |
Recommended | The two-digit day defined in the <Checkin> element
of the Hotel Price Feed. For example, "20". |
CHECKINDAY-OF-WEEK |
Optional | The day of the week ("Monday" to "Sunday") on which the check-in takes place, in the hotel's timezone. For example, "Tuesday". |
CHECKINMONTH |
Recommended | The two-digit month defined in the <Checkin>
element of the Hotel Price Feed. For example, "06". |
CHECKINYEAR |
Recommended | The four-digit year defined in the <Checkin>
element of the Hotel Price Feed. For example, "2017". |
CHECKOUTDAY |
Recommended | The two-digit day calculated from the <Nights> and
<Checkin> elements of the Hotel Price Feed. For
example, "23". |
CHECKOUTMONTH |
Recommended | The two-digit month calculated from the <Nights>
and <Checkin> elements of the Hotel Price Feed. For
example, "07". |
CHECKOUTYEAR |
Recommended | The four-digit year calculated from the <Nights>
and <Checkin> elements of the Hotel Price Feed. For
example, "2017". |
CHILD-AGE |
Recommended (must be provided for child occupancy pricing) | The maximum age of each child as specified in the
<Child "age"> elements of the price feed.
This variable must be used in conjunction with a
FOR-EACH-CHILD-AGE conditional block. |
CHILD-INDEX |
Optional | A 0-indexed loop variable representing a counter for each child
occupant and child age specified in the itinerary. While not mandatory,
this variable can only be used in conjunction with a
FOR-EACH-CHILD-AGE conditional block.
|
CLICK-TYPE |
Optional | Indicates whether the user clicked on an listing for a standard hotel
rate or for a Room Bundle. Possible values are:
|
CLOSE-RATE-RULE-IDS |
Optional (only applies if you are using conditional or private rates) | 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 private rates will always be populated here when a corresponding UI treatment is shown to the end user. |
CUSTOM[1‑5] |
Optional | The values of the custom fields that are defined in a Transaction
message's <Result> element. There is a limit of
200 characters per custom field. For more information, refer to
Overview of Transaction Messages. |
DATE-TYPE |
Optional | Indicates whether the user selected the default date or specified a
date when searching. Possible values are:
|
GOOGLE-SITE |
Optional | The Google property on which a user viewed your hotel-pricing data.
Possible values are:
|
LENGTH |
Recommended | 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 |
Recommended (must be used with the NUM-CHILDREN or
FOR-EACH-CHILD-AGE condition) |
The number of adult occupants specified for the itinerary by the user.
This variable must be used in conjunction with
NUM-CHILDREN , FOR-EACH-CHILD-AGE , or both. |
NUM-CHILDREN |
Recommended | The number of child occupants (0-17 yrs old) specified for the
itinerary by the user. NUM-CHILDREN ,
FOR-EACH-CHILD-AGE , or both are required to successfully
participate in itineraries with child occupants. |
NUM-GUESTS |
Recommended (if you don't send child occupancy pricing) | The total number of occupants, both adults and children, specified for
the itinerary by the user. This value is a sum of the
NUM-ADULTS and NUM-CHILDREN values. To
maximize participation, it is strongly recommended to utilize both
NUM-ADULTS and NUM-CHILDREN instead. |
PARTNER-CURRENCY |
Optional | 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 |
Recommended | The unique identifier for the hotel defined by the
<id> element in the Hotel List Feed. |
PARTNER-ROOM-ID |
Recommended (applies if you used RoomBundles) | 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 |
Optional (only applies to Ads) | 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 |
(Optional) | 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 |
(Optional) | 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". |
PROMO-CODE |
(Optional) | (For ARI feeds only) If you use
ARI promotions, this
variable is assigned the value of the id attribute of the
applied <Promotion> .
|
RATE-PLAN-ID |
Recommended (only applies if you use RoomBundles) | The ID as defined by the <RatePlanID> element in a
price feed's <RoomBundle> block. The
<RatePlanID> represents the unique identifier
for a room and package data combination. For more
information, see Room Bundles. |
RATE-RULE-ID |
Recommended (only applies if you use conditional rates or private rates) | The ID as defined by the rate_rule_id attribute within a
price feed's <Rate> block. For more information,
refer to Conditional Rates. |
USER-COUNTRY |
Recommended | 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 |
Recommended | 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 |
Recommended | The end-user's device type. The value of USER-DEVICE can
be one of the following:
The value of the |
USER-LANGUAGE |
Recommended | 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". |
USER-LIST-ID (defined in Google Ads) |
Optional (only applies if you use Audience Lists in Google Ads) | The Google Ads user list ID of the audience list to which the end-user belongs. Audience lists are used as a basis for setting bid adjustments. If the user is part of multiple audience lists, the audience list with the largest bid adjustment is selected. Ties among audiences with the largest bid adjustment are decided randomly. |
VERIFICATION |
Optional | A boolean that verifies if the link was generated by Google. "true" if the link was generated by Google. Otherwise, "false". |
Using conditional logic in URLs
You can use special directives in the <URL>
element of a
landing pages file to conditionally build endpoints.
The conditional logic supports the following statements:
- if_statement: If
true
, then the values that follow this condition are inserted into the URL. Otherwise, the values following theELSE
directive are inserted. - for_statement: Creates a FOR loop condition that iterates based on the number of values provided.
IF and FOR statements include the following:
Condition | Recommended/optional | Description |
---|---|---|
IF-AD-CLICK (Hotel Ads only) |
Optional | Resolves to
true if the user click originated from an ad; otherwise
resolves to false . |
IF-CLICK-TYPE-HOTEL |
Optional | Resolves to true if the
user clicked on a listing for a hotel; otherwise resolves to
false . |
IF-CLICK-TYPE-ROOM |
Optional | Resolves to true if the
user clicked on a listing for a Room Bundle;
otherwise resolves to false . |
IF-CLOSE-RATE-RULE-IDS |
Optional | Resolves to true if
one or more conditional rates were unavailable because the user was
ineligible. Otherwise, resolves to false . Will
always be true if a private
rate UI treatment was shown to the end user. |
IF-DEFAULT-RATE |
Optional | Resolves to true if the user
clicked on a hotel listing where default dates were used; otherwise resolves
to false . |
IF-HOTEL-CAMPAIGN |
Optional | Resolves to
true if the ad click originated from a hotel campaign;
otherwise resolves to false. This distinction is helpful for partners
that have multiple campaign types present in Google Ads to allocate
attribution. |
IF-PAYMENT-ID (Hotel Ads only) |
Recommended (if you use pay-per-stay Google Ads campaigns) | Resolves to
true for hotels in the Pay-Per-Stay (PPS) commissions
program; otherwise false . |
IF-PROMO-CODE |
Optional | Resolves to true if the user
clicked on a rate based on an ARI promotion; otherwise resolves to
false . |
IF-PROMOTED (Hotel Ads only) |
Recommended (if you use Promoted hotels) | Resolves to true
if the user clicked on a Property Promotion Ad; otherwise resolves
to false . |
IF-RATE-RULE-ID |
Optional | Resolves to true if the
user selected a conditional rate; otherwise
resolves to false . |
IF-USER-LIST-ID (defined in Google Ads) |
Optional | Resolves to
true if the user is a member of a Google Ads customer list
ID you specified when setting bid multipliers for audience lists;
otherwise resolves to false . |
ELSE |
Recommended (if you use any conditional IF statements) | If the previous condition is not met, then the values that follow this condition are inserted into the URL. |
END-IF |
Optional (required if you have any IF conditional statements) | Ends the IF statement conditional block. |
FOR-EACH-CHILD-AGE |
Optional (required for child occupancy pricing) | Executes one time for each
<Child "age"> element in the price feed. For
example, if the <OccupancyDetails> include the two elements
<Child age="17"> and <Child age="17"> ,
then the directive executes two times. |
END-FOR-EACH |
Optional (required if using FOR-EACH block) | Ends the FOR-EACH statement conditional block. |
IF-AD-CLICK example (Hotel Ads only)
You can construct a conditional block that checks if the user clicked an ad to redirect to your landing page.
The following example uses this directive in a landing page file:
<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)(IF-AD-CLICK)&adType=1(ELSE)&adType=0(ENDIF)</URL>
In this example, if the end-user did not click on an ad, the result is the following URL:
https://www.partner.com?hid=123&adType=0
If the end-user did click on an ad, the result is the following URL:
https://www.partner.com?hid=123&adType=1
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 landing pages file:
<URL>https://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:
https://partner.com/landing_room?hid=123
If the end-user did not select a Room Bundle, the result is the following URL:
https://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 landing pages file:
<URL>https://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:
https://partner.com/landing?hid=123
If the end-user selected a Room Bundle, the result is the following URL:
https://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>https://partner.com?hotelID=(PARTNER-HOTEL-ID) &checkinDay=(CHECKINDAY)&checkinMonth=(CHECKINMONTH)&checkinYear=(CHECKINYEAR) &nights=(LENGTH)(IF-DEFAULT-DATE)&popup_datepicker=true(ELSE) &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):
https://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:
https://partner.com?hotelID=123&checkinDay=23&checkinMonth=07&checkinYear=2017&nights=2&popup_datepicker=false
IF-HOTEL-CAMPAIGN example (Hotel Ads only)
You can construct a conditional block that checks if the user clicked an ad that originated from a hotel campaign.
The following example uses this directive in a landing page file:
<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)(IF-HOTEL-CAMPAIGN)&aid=(CAMPAIGN-ID)(ELSE)(ENDIF)</URL>
In this example, if the end-user clicks on a hotel campaign URL, the result is the following URL:
https://www.partner.com?hid=123&aid=12345678
If the click is not on a hotel campaign URL, the result is the following URL:
https://www.partner.com?hid=123
IF-PAYMENT-ID example (Hotel Ads only)
Use the IF-PAYMENT-ID
conditional statement to vary the URL
based on whether the click is a result of the PPS commissions program
or not. The example below enquires if a click came from the PPS commissions
program and assigns a value to the booking_source
parameter based
upon the result:
<URL>https://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:
https://partner.com?hid=123&booking_source=commissions
-
If an IATA number has been assigned to Google:
https://partner.com?hid=123&booking_source=01234567
Otherwise, the result is the following URL:
https://partner.com?hid=123&booking_source=cpc
IF-PROMOTED example (Hotel Ads only)
You can construct a conditional block that checks if the user clicked on a Property Promotion Ad.
The following example uses this directive in a landing pages file:
<URL>https://partner.com/(IF-PROMOTED)1(ELSE)0(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>
In this example, if the end-user selected a Property Promotion Ad, the result is the following URL:
https://partner.com/1?hid=123
If the end-user didn't select a Property Promotion Ad, the result is the following URL:
https://partner.com/0?hid=123
IF-RATE-RULE-ID example
You can construct a conditional block that checks if the user selected a
conditional 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 landing pages file:
<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)(IF-RATE-RULE-ID)&customerType=42(ELSE)(ENDIF)</URL>
In this example, if the end-user did not select a conditional rate, the result is the following URL:
https://www.partner.com?hid=123
If the end-user selected a conditional rate, the result is the following URL:
https://www.partner.com?hid=123&customerType=42
IF-USER-LIST-ID example (defined in Google Ads)
If you set bid multipliers for audience lists in a Hotel campaign in Google
Ads, you can use IF-USER-LIST-ID
in conjunction with
USER-LIST-ID
to set a parameter on your website for a customer
who belongs to a certain Google Ads audience list. You may want to do so for
tracking purposes or to customize your website for members of audience lists.
Example:
<URL>https://partner.com/?hid=(PARTNER-HOTEL-ID)(IF-USER-LIST-ID)&audience_list=(USER-LIST-ID)(ELSE)(ENDIF)</URL>
In this example, if the end-user wasn’t a member of an audience list, the result is the following URL:
https://www.partner.com?hid=123
If the end-user was a member of the audience list 12345678, the result is the following URL:
https://www.partner.com?hid=123&audience_list=12345678
FOR-EACH-CHILD-AGE example
You can construct a conditional block that populates the maximum age of each child occupant, as specified in the Hotel Price Feed.
The following example uses this directive in a landing pages file:
<URL>https://partner.com?adults=(NUM-ADULTS)&children=(NUM-CHILDREN)(FOR-EACH-CHILD-AGE)&age=(CHILD-INDEX)_(CHILD-AGE)(END-FOR-EACH)&hid=(PARTNER-HOTEL-ID)</URL>
In this example, if the itinerary had 2 adults and 2 children with ages 0 and 17 respectively, the result is the following URL:
https://www.partner.com?adults=2&children=2&age=0_0&age=1_17&hid=123
If the itinerary had 2 adults and 0 children then the result is the following URL:
https://www.partner.com?adults=2&children=0&hid=123
General rules when building URLs
All variables are optional. You are not required to insert any variables in your landing page 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 landing pages 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
landing pages file format is XML), you must use the encoded
entity "&" in its place. The final output renders an actual "&"
character. For example:
<!-- Do this: --> <URL>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&nights=(LENGTH)</URL> <!-- Do NOT do this: --> <URL>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&nights=(LENGTH)</URL>
You must also URL-encode special characters that you might include in the landing page 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, consult URL Encoding Table.
- space (" "): Replace space characters with "%20;" in the
- Values for a single parameter can be constructed from multiple variables.
The following example constructs a single parameter,
checkinDate
, from theCHECKINDAY
,CHECKINMONTH
, andCHECKINYEAR
variables:<URL>https://www.partnerdomain.com?checkinDate=(CHECKINDAY)%2F;(CHECKINMONTH)%2F;(CHECKINYEAR)</URL>
This example results in a URL that might look like the following:
https://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.