Reports API v1.2

The Reports API gives you access to reports that contain various data about your Hotel Ads account.

Overview

The Reports API lets you either specify a report to get, or list all available reports.

When using the Reports API, you typically decide on the report type, execute a List Reports request to get a list of dates for that report type, and then issue a Get Report report that requests the report for the given dates.

The standard report type is the Performance with Conversion Metrics, which includes the performance report, plus additional conversion tracking-specific fields. If no report_type value is provided, Google returns the dates that are available for this report type. For more information, see Performance Report.

In addition, you can use the Reports API to get the following other types of reports:

Report Type Description Link
Bid Simulation Gives you a quick view of the overall CPC percentage bidding landscape and helps you determine what bids to make. This is the same report as the Bid Sumlation CPC Percentage Report. More info
Bid Simulation CPC Percentage Report Gives you a quick view of the overall CPC percentage bidding landscape and helps you determine what bids to make. More info
Bid Simulation Target ROAS Report Gives you a quick view of the overall target ROAS bidding landscape and helps you determine what bids to make. More info
Bid Simulation Commission Guest Stay Report Gives you a quick view of the overall commission guest stay bidding landscape and helps you determine what bids to make. More info
Bookings Lists the bookings received through conversion tracking. More info
Budget Lists budget performance metrics and estimated missed opportunities. More info
Performance with Conversion Metrics Includes the performance report, plus additional conversion tracking-specific fields. If no report_type value is provided, Google returns the dates that are available for this report type. More Info
Price Accuracy Lists a sample set of itineraries and the date/times when prices for those itineraries were fetched and cached. More info
Room Types Lists Room Type fields. More info
Top Opportunity Lists opportunities you might have missed per hotel over a 7-day period. More info
Top Opportunity with Breakdown Lists opportunities you might have missed per hotel over a 7-day period. Includes breakdowns of missed opportunities by type. More info

For general information about reports, see Reporting Overview.

List Reports endpoint

The List Reports endpoint gets a list of dates that are available for the specified report type. You can then request a report that uses the available dates that are returned by this endpoint. Results are returned in JSON format only.

Endpoint

  • Path: /reports

Input parameters

The following table lists the input parameters for Reports API requests:

Input Parameter Required? Description
partner Optional Identifies the specific account for which you are requesting data. The value of this parameter is the partner name (not the partner ID, which is a number). If you do not know the partner name, contact us to request it.
report_type Optional Indicates the report type for which dates will be returned. You can set the value of this parameter to one of the following values:
  • BID_SIMULATION
  • BID_SIMULATION_CPC_PERCENTAGE
  • BID_SIMULATION_TARGET_ROAS
  • BID_SIMULATION_COMMISSION_GUEST_STAY
  • BOOKING
  • BUDGET
  • PERFORMANCE_WITH_CONVERSION_METRICS (default)
  • PRICE_ACCURACY
  • ROOMTYPES
  • TOP_OPPORTUNITY_7_DAY
  • TOP_OPPORTUNITY_7_DAY_WITH_BREAKDOWN

The following example request gets a list of Booking Reports:

https://www.googleapis.com/travelpartner/v1.2/reports?report_type=BOOKING

List Reports Results

The following example response shows the dates for which Booking reports are available:

{ "kind": "travelpartner#reportsList",
  "date": [ "20150323",
            "20150324",
            "20150325",
            "20150326",
            "20150327",
            "20150329",
            "20150330",
            "20150331",
            "20150401",
            "20150402",
            "20150403"
          ]
}

The date array lists dates in the format YYYYMMDD, where YYYY is the four-digit year, MM is the two-digit month, and DD is the two-digit day. In the example above, the List Reports call returned the dates for which Booking reports are available. These are the days between March 23, 2015 and April 4th, 2015, inclusive.

If the response does not contain a date object, then there are no reports available for that type of report; for example:

{
  "kind": "travelpartner#reportsList"
}

Get Report endpoint

The Get Report endpoint in the Reports API requests a specific report for a given date. The report's data is returned as comma separated values (CSV) only.

Endpoint

  • Path: /reports/get

Input Parameters

Input Parameter Required? Description
altRequired Specifies the results format. Set to "csv" to indicate comma-separated values (CSV).
dateRequiredThe date (or starting date in the case of a date range) for which you want to retrieve the report, in the format YYYYMMDD.
end_date Optional The end date for a date range, in the format YYYYMMDD. If you want data for a single day only, do not set this value.
nextrowOptionalSpecifies an offset for your query. For more information, see Using Offsets.
report_typeOptionalSpecifies the type of report to get. Valid values for the report_type parameter are:
  • BID_SIMULATION
  • BID_SIMULATION_CPC_PERCENTAGE
  • BID_SIMULATION_TARGET_ROAS
  • BID_SIMULATION_COMMISSION_GUEST_STAY
  • PERFORMANCE_WITH_CONVERSION_METRICS (default)
  • BOOKING
  • BUDGET
  • TOP_OPPORTUNITY_7_DAY
  • TOP_OPPORTUNITY_7_DAY_WITH_BREAKDOWN
  • PRICE_ACCURACY
  • ROOMTYPES

Each of these values corresponds to a report type described in the Reporting Guide. If you do not set the value of the parameter, then the Reports API returns a list of dates for which the PERFORMANCE_WITH_CONVERSION_METRICS report is available.

Get Report Example Queries

The following example gets the PERFORMANCE_WITH_CONVERSION_METRICS report for April 11, 2015:

https://www.googleapis.com/travelpartner/v1.2/reports/get?alt=csv&date=20150411&report_type=PERFORMANCE_WITH_CONVERSION_METRICS

The following example gets 5 days of Budget data by setting the values of both the date and end_date parameters:

https://www.googleapis.com/travelpartner/v1.2/reports/get?alt=csv&date=20150210&end_date=20150215&report_type=BUDGET

Get Report Results

The following example response includes the contents of the Performance Report:

NEXTROW: 9
property,country,device_type,hotel_id,check_in_date,length_of_stay,price_bucket,slot,slot_position,ad_position,room_bundle,impressions,eligible_impressions,clicks,billing_cost_usd,conversions,booked_base_price_usd,booked_total_price_usd,booked_length_of_stay,booking_window_days
localuniversal,US,tablet,ABQAA,20150213,1,0,A,0,1,FALSE,1,1,0,0,0,0,0,0,0 localuniversal,US,desktop,ABQAP,20150217,1,-1,Z,-1,-1,FALSE,0,1,0,0,0,0,0,0,0
localuniversal,NG,desktop,ABUHI,20150212,2,0,A,0,1,FALSE,1,1,0,0,0,0,0,0,0 localuniversal,NG,desktop,ABUHI,20150222,1,0,A,0,1,FALSE,6,6,0,0,0,0,0,0,0
localuniversal,NG,mobile,ABUHI,20150222,1,0,A,0,1,FALSE,1,1,0,0,0,0,0,0,0 localuniversal,NG,tablet,ABUHI,20150222,1,0,A,0,1,FALSE,1,1,0,0,0,0,0,0,0
localuniversal,GB,desktop,ABZAC,20150212,1,0,M,1,3,TRUE,0,1,0,0,0,0,0,0,0 localuniversal,GB,mobile,ABZAC,20150222,1,0,M,1,3,TRUE,0,3,0,0,0,0,0,0,0 

CSV files returned by the Reports API include the column names as the first row in the response.

For more information about the contents of each of the report types, see Reporting Guide.

Reports API changes

There are no differences between version 1.1 (sunsetted) and version 1.2 of the Reports API.

Send feedback about...

Need help? Visit our support page.