Version 2.0 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 Hotel Prices accounts. The services make it easier to track properties and, if you participate in bidding, to submit bids and assess the performance of your account.
API summary
The Travel Partner API endpoints uses RESTful syntax via HTTPS calls. The base URL for all API 2.0 requests is:
https://www.googleapis.com/travelpartner/v2.0/account_id
The following table summarizes the API endpoints for the Travel Partner API 2.0:
API Name | Endpoint | Available to | Description |
---|---|---|---|
Feed Status API | /feed_status |
Hotel Ads & Hotel Prices | Gets a report of your feeds, including errors and warnings that Google encountered when processing those feeds. |
Hotels API | /hotels |
Hotel Ads & Hotel Prices | Lists properties that are in your Hotel List Feed, including those that are over-clustered or have other data quality issues. |
Prices API | /prices |
Hotel Ads & Hotel Prices | Returns itineraries and their associated prices for your properties. |
Migrating from 1.x to 2.0
When moving your API tools from versions 1.2 or earlier to 2.0, keep the following in mind:
What's changed:
- All requests require your account ID in the query path. The account ID can be the ID of a master or sub account.
- To submit bids for hotels in a sub account, you must use the Bids 2.0 API.
- The endpoints have changed to better represent RESTful services. For
example:
Do this (2.0):
https://www.googleapis.com/travelpartner/v2.0/account_id/reports
Not this (1.x):
https://www.googleapis.com/travelpartner/v1.2/reports/get
- Some APIs support write operations. These include:
- Bids API: You can set bids at the account default, Hotel Group, or individual hotel level.
- Budgets API: You can set an account's daily spending cap and max bid cap.
- Groups API: You can create new Hotel Groups, and add and remove hotels to and from those groups.
What hasn't changed:
- The way that you authenticate against the APIs is the same from 1.2 to 2.0. You still use OAuth 2.0.
- You can still pass
nextrow
andmaxresults
parameters in the query.
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.0 | N/A | N/A |
v1.2 | N/A | N/A |
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 withinbids
:api_request_url/bids?fields=bids/base_bid_source
- Get multiple objects using commas. The following example gets
base_bid_source
which is nested withinbids
, andmultiplier_source
which is also nested withinbids
: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 thebid/multipliers
objects for each item in thebids
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.0/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
All 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 sub accounts 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 Console. For more information, see Viewing Sub Account Information.