Using the Travel Partner v2.1 APIs

Version 2.1 of the Travel Partner Application Programming Interface (API) is a collection of RESTful services that let you programmatically access bidding, pricing, hotel, and diagnostic reporting data about your accounts.

API v2.1 summary

The Travel Partner API endpoints uses RESTful syntax via HTTPS calls. The base URL for all API 2.1 requests is:

https://www.googleapis.com/travelpartner/v2.1/account_or_campaign_id

The following table summarizes the API endpoints for the Travel Partner API 2.1:

API Name Endpoints Description
Account Assignments API GET /assignments
PUT /assignments/destination_account_id
Lists all hotels in the specified accounts or sub accounts and lets you assign hotels to a particular account or sub account.
Bids API GET /bids
PUT /bids/update
Lists your submitted bids and makes real-time bid updates.

Budgets API GET /budgets
PUT /budgets/update
Gets your account budget settings and sets new budget values.

Campaigns API GET  /campaigns
GET  /campaigns/campaign_id
POST /campaigns/create
PUT  /campaigns/campaign_id/update
Gets a list of campaigns, views the details of campaigns, creates new campaigns, and updates existing campaigns.

You cannot delete a campaign with this API, but at any time you can pause the campaign so that its hotels no longer participate in auctions.

Groups API GET  /groups
GET  /groups/group_id
GET  /groups/group_id/ungrouped
POST /groups/group_id/create/group_name
PUT  /groups/group_id/add_hotels
PUT  /groups/group_id/remove_hotels
PUT  /groups/group_id/rename/group_name
DELETE /groups/group_id/delete
GET  /groups/group_id/lookup/hotel_name
Creates and deletes Hotel Groups, as well as adds and removes hotels to and from those groups.

Hotels API GET /hotels Lists properties that are in your Hotel List Feed, including those that are over-clustered or have other data quality issues.
Prices API GET /prices/hotel_id Returns itineraries and their associated prices for your properties.
Reconciliation Reports API GET  /reconciliation_reports
GET  /reconciliation_reports/date_time/file_name
POST /reconciliation_reports
POST /reconciliation_reports/validate
Views, validates, and uploads your commissions reconciliation reports, if you are in the Google Hotal Ads Commissions Program (GHACP).
Reports API GET /reports
GET /reports/report_type
GET /reports/report_type/report_date
Lists available reports or gets a report for the specified date.
Scorecard API GET /scorecard/query_type Gets Scorecard data for the specified account.
Sub Account Info API GET /subaccounts Gets billing details and other info about an account.

The Feed Status, Hotels, and Prices APIs are available to both Hotel Ads and Hotel Prices. All other APIs are available only to Hotel Ads.

API change summary

The following table summarizes the changes to version 2.1 of the API:

API Account/Campaign in URL Summary
Account Assignments API Account ID only

Changes to v2.1 of the Account Assignments API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Bids API Campaign ID only

Changes to v2.1 of the Bids API include the following:

  • The automatic_multipliers field has been renamed to enhanced_cpc. (Automatic Bid Multipliers are now known as enhanced CPC or eCPC). Like ABM, you cannot enable or disable eCPC at the individual hotel level. Unlike ABM, eCPC:

    • Is a campaign-level setting only; if enabled, eCPC is used for all bids in that campaign.
    • Can be used in combination with bid multipliers.
    • Cannot be enabled or disabled at the Ad Group level.
  • You cannot set the maximum bid on the campaign with the Bids API.
  • Bids can only be on hotels or groups within the context of a campaign.
  • There is no longer an Account Default Bid. You can set a campaign default bid with the Bids API or Campaigns API.
  • You can now pause bidding at the campaign, Ad Group, or hotel level with the is_paused field in a bid update.
  • You no longer specify the account or sub account ID in the request URL. Instead, you specify the campaign ID.
  • Hotel-level Bid Multipliers are no longer supported.
  • Some ranges of valid values for Bid Multipliers have changed.
  • The sites Bid Multiplier has been removed.
  • Bids must adhere to the campaign bidding rules.
  • You set a campaign's daily spending cap using the Campaigns API.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Budgets API Account ID

Changes to version 2.1 of the Budgets API include the following:

  • You now set an unlimited budget by setting cleared to true.
  • The maximum bid cap is no longer supported for sub accounts. As a result, it has been removed from the Budgets API. You can set a max bid cap at the campaign level by using the Campaigns API.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Campaigns API Account ID only

Changes to version 2.1 of the Campaigns API include the following:

  • You cannot set the maximum bid at the campaign level.
  • campaign_budget.account_daily has been renamed to daily_spending_cap.
  • To explicitly clear the campaign's spending cap, set daily_spending_cap.cleared to true.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
  • Responses now include a campaign_last_update_timestamp_micro field.
Groups API Account or campaign ID

Changes to version 2.1 of the Groups API include the following:

  • All Groups API endpoints now take either a campaign or account ID. Previously, they accepted only account IDs.
  • Each campaign has one ungrouped group that cannot be deleted or renamed. You can access this group by its ID; you cannot access it with the ungrouped path parameter. For accounts and sub accounts, you can use the ungrouped path parameter to access this special group.
  • The ungrouped group show in the group list with an empty name.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
  • Responses now include a group_last_update_timestamp_micro field.
Hotels API Account ID only

Changes to version 2.1 of the Hotels API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Prices API Account ID only

Changes to version 2.1 of the Prices API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Reconciliation Reports API Account ID only

Changes to version 2.1 of the Reconciliation API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Reports API Account or campaign ID

Changes to version 2.1 of the Reports API include the following:

  • For some reports, you can specify an account, sub account, or campaign ID in the API endpoint's URL. Previously, you could only specify an account or sub account ID.
  • There is a new report type, campaign_opportunity.
  • There is a new report type, cross_device_conversions, that you can request.
  • You can now request a performance_by_click_type report.
  • The following reports can include data rolled up by campaign:

    • bid_simulation_cpc_percentage
    • bid_simulation_commission_guest_stay
    • bid_simulation_target_roas
    • book_on_google
    • booking
    • budget
    • click_to_call
    • cross_device_conversions
    • limited_offers_volume
    • performance
    • performance_by_click_type
  • The bid_simulation report has been removed. It was the same as the bid_simulation_cpc_percentage report.
  • The performance_with_date_type report has been removed. The performance report contains the information that was previously in that report.
  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Scorecard API Account ID only

Changes to version 2.1 of the Scorecard API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...
Sub Account API Account ID only

Changes to version 2.1 of the Sub Account Info API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...

Deprecation

Google supports at least the two most recent API versions at any given time. When a new version is released, the version that is now two releases back will be deprecated and scheduled for sunsetting.

  • Deprecated indicates that the version of the API will continue to function as expected, but may not be updated with new features or bug fixes. In addition, when a version is deprecated, a sunset date is determined.
  • Sunsetted indicates that the version of the API is removed and is no longer available. The minimum amount of time between deprecation and sunsetting is 3 months.

The following table shows the current schedule of API versions, as well as expected deprecation and sunset dates:

Version Deprecation Date Sunset Date
v2.1 N/A N/A
v2.0 (Bids API) February 2018 May 2018
v2.0 (all other APIs) N/A N/A
v1.2 February 2018 May 2018
v1.1 June 2016 October 2016
v1.0 April 2015 October 2015

Improving performance with partial responses

The Hotels APIs support a simple syntax that you can use to get partial responses with your API calls. You do this by specifying the names of the objects that you want with the fields query string parameter.

For example, rather than getting the entire response for a Bids API request, you can get just the bids objects, as the following example shows:

api_request_url/bids?fields=bids

The fields parameter supports the following syntax:

  • Use "/" separators to select objects that are nested. The following example gets base_bid_source which is nested within bids:

    api_request_url/bids?fields=bids/base_bid_source
  • Get multiple objects using commas. The following example gets base_bid_source which is nested within bids, and multiplier_source which is also nested within bids:

    api_request_url/bids?fields=bids/base_bid_source,bids/multiplier_source
  • Use wildcard characters (*) to select all objects. The following example gets all objects nested in bids/bid/multipliers:

    api_request_url/bids?fields=bids/bid/multipliers/*
  • Specify sub-selections with "()". The following example gets the base_bid_source, multiplier_source, and the bid/multipliers objects for each item in the bids array:

    api_request_url/bids?fields=bids(base_bid_source,multiplier_source,bid/multipliers)

Using offsets

When a set of data returned by the Travel Partner API is large enough, you must use an offset to page through the results. You do this with the nextrow query string parameter, as the following example shows:

https://www.googleapis.com/travelpartner/v2.1/420042/hotels?nextrow=131073

The nextrow parameter specifies an offset value which is a unique token that you pass to the API on your second and subsequent requests. When you include nextrow in your query, the Travel Partner API applies it to the request and gives you the next set of results, starting with the value of nextrow.

The value of nextrow is not an integer that simply defines an index offset. Instead, it is a unique identifier that the Travel Partner API uses to determine which set of results to use. As a result, your first request should never include this parameter. Responses that are incomplete will have NEXTROW:value as the first line in each response; for example:

NEXTROW: 131073

To offset your next request, you extract the value of NEXTROW from the response body and set it as the value of the nextrow query string parameter in your next request.

Authentication

To access the Travel Partner API, clients must authenticate using OAuth2 authentication.

For an example application and additional information about using OAuth to connect to the Travel Partner API, see API Authentication.

Specifying an account

Some endpoints take an account ID in the URL. The account ID can be a parent account or a sub account. If it is a parent account, then all data from that account's children is aggregated and included in the response.

If you do not know your account ID, you can use the Account Info view on the Account tab in the Hotel Ads Center. For more information, see Viewing Sub Account Information.