Scorecard API v2.0

The Scorecard API returns values displayed in the Hotel Ads Center's Scorecard view.

Path

base_path/api_version/account_id/scorecard/query_type

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.0
account_id A parent account or sub account ID.
query_type (Required) Specifies the type of details to get.

Query String Parameters

None.

Supported Methods

HTTP Method Description
GET Gets your account's scorecard values.

Examples

Gets the price accuracy score for the specified account:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/scorecard/price_accuracy_score

Getting scorecard values

To get an account's scorecard values, submit a GET request by using the following syntax:

GET https://www.googleapis.com/travelpartner/v2.0/account_id/scorecard/query_type

The following example gets the price accuracy score for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.0/4200042/scorecard/price_accuracy_score

The following table describes the possible values for query_type:

Query String Parameter Description
price_accuracy_score Returns the Price Accuracy Score of the specified account.
hotel_list_stats Returns details about your Hotel List Feed that are displayed in the Account Health section of the Hotel Ads Center's Scorecard view.
price_coverage_stats Returns the coverage statistics that are displayed in the Account Health section of the Hotel Ads Center's Scorecard view. For more information, see the Prices Coverage Report section.
price_coverage_stats_history Returns the coverage statistics history that is displayed in the Account Health section of the Hotel Ads Center's Scorecard view. For more information, see the Prices Coverage Report section.
performance_stats Returns the performance statistics that are displayed in the Performance section of the Hotel Ads Center's Scorecard view. For more information, see the Performance Report with Conversion Metrics section.
opportunity_stats Returns the values displayed on the Opportunity section of the Hotel Ads Center's Scorecard view. For more information, see the Opportunity Report section.
configuration_stats Indicates whether conversion tracking is enabled for the specified account.

All successful responses include the Scorecard information, as well as an etag object. This object is used for internal debugging. You can ignore its value.

Scorecard API examples

This section describes each type of scorecard detail you can get from the Scorecard API.

Price accuracy score

When you specify price_accuracy_score as the query_type, the Scorecard API returns your price accuracy score.

The following shows a sample price accuracy score response:

{
    "resource": {
        "priceaccuracy_stats": {
            "score": {
                "state": "EXCELLENT"
            }
        },
        "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
    }
}

The value of state can be EXCELLENT, GOOD, POOR, AT RISK, or FAILED. For more information, see Price Accuracy Policy.

Hotel list stats

When you specify hotel_list_stats as the query_type, the Scorecard API returns a hotel_list_stats object with various attributes that describe the current status of your Hotel List Feed.

The following shows a sample hotel list stats response:

{
  "resource": {
    "hotel_list_stats": {
      "last_update_timestamp_us": "0",
      "matched_properties_count": "0",
      "unmatched_properties_count": "0",
      "unmatched_properties_with_errors_count": "0",
      "over_clustered_properties_count": "0",
      "over_clustered_properties_with_errors_count": "0",
      "last_manifest_update_timestamp_us": "1464696157242776",
      "last_feed_submit_update_timestamp_us": "0"
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

The following table describes the properties in the hotel list stats response:

Property Description
matched_properties_count The total number of properties in your Hotel List Feed that match Google's manifest.
unmatched_properties_count The number of properties in your Hotel List Feed that are considered unmatched. Unmatched hotels are those whose entries in your Hotel List Feed do not match any entries in Google's manifest.

For more information, see Matching Report.

unmatched_properties_with_errors_count The number of unmatched properties in your Hotel List Feed that have data-related errors, such as missing required information.

For more information, see Matching Report.

over_clustered_properties_count The total number of hotels in your Hotel List Feed that are considered overclustered. Overclustered hotels are those that appear to be duplicates of other hotels in your Hotel List Feed. This is often due to incomplete or duplicate information in one or more entries.

For more information, see Manual Match Fix tool.

over_clustered_properties_with_errors_count The number of overclustered properties in your Hotel List Feed that have data-related errors, such as missing required information.

For more information, see Manual Match Fix tool.

last_manifest_update_timestamp_us The last time, in microseconds since Jan 1, 1970, that Google's hotel manufest was updated. This is updated approximately once per week.
last_feed_submit_update_timestamp_us The last time, in microseconds since Jan 1, 1970, that you submitted your Hotel List Feed.
last_update_timestamp_us The same as last_feed_submit_update_timestamp_us.

For more information, see Hotel List Feed.

Price coverage stats

When you specify price_coverage_stats as the query_type, the Scorecard API returns price_coverage_stats object that contains details about the target account's price coverage.

The following shows a truncated price coverage stats response:

{
  "resource": {
    "price_coverage_stats": {
      "coverage": {
        "partner_name": "Partner 1",
        "calculated_date": "2016-06-22",
        "properties_matched": 28161,
        "price_coverage_binary_percentage": 85.941042906969,
        "price_coverage_percentage": 69.1880769765058,
        "bucket_price_coverage": [
          {
            "arrival_date_bucket": "DAY_0_TO_30",
            "length_of_stay_bucket": "LOS_1_TO_7",
            "price_coverage_count": "7871198",
            "price_coverage_percentage": 62.5960405433301
          },
          {
            "arrival_date_bucket": "DAY_0_TO_30",
            "length_of_stay_bucket": "LOS_8_TO_14",
            "price_coverage_count": "5348297",
            "price_coverage_percentage": 51.87989530881325
          }
        ]
      }
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

The overall stats for the account are given in the coverage object.

The following table describes each of the top-level fields of the coverage object:

Field Description
partner_name The name of the partner for which this scorecard data applies.
calculated_date The date on which the calculations were made, in YYYY-MM-DD format.
properties_matched The total number of properties that have prices for the given itineraries.
price_coverage_binary_percentage The number of hotels which have at least one price for the calculation period, divided by properties_matched.
price_coverage_percentage The overall price coverage for your account. This value is the sum of all the hotel prices for the calculation period and length of stay, divided by properties_matched times 330 (advanced book window) times 30 (length of stay).

The bucket_price_coverage object contains an array of stats for each combination of advanced booking windows and length of stay. The following table describes the fields within each object in the array:

Field Description
arrival_date_bucket The number of days for the advanced booking window, in ranges from 0 to 30, 31 to 60, and so on.
length_of_stay_bucket The number of nights for the stay, in ranges from 1 to 7 and 8 to 14.
price_coverage_count The number of prices that matched the values in the arrival_date_bucket and length_of_stay_bucket ranges.
price_coverage_percentage The percent of itineraries for which you have coverage, for the given ranges.

For more information, see Prices Coverage Report.

Price coverage stats history

When you specify price_coverage_stats_history as the query_type, the Scorecard API returns a price_coverage_stats_history object that details recent changes to your price coverage stats.

The following shows a truncated price coverage stats history response:

{
  "resource": {
    "price_coverage_stats_history": {
      "coverage": [
        {
          "partner_name": "Partner 1",
          "calculated_date": "2016-05-24",
          "properties_matched": 14319,
          "price_coverage_binary_percentage": 80.0439742425095,
          "price_coverage_percentage": 68.338516015616,
          "bucket_price_coverage": [
            {
              "arrival_date_bucket": "DAY_0_TO_30",
              "length_of_stay_bucket": "LOS_1_TO_7",
              "price_coverage_count": "1623625",
              "price_coverage_percentage": 62.9989484413296
            }
          ]
        },
        {
          "partner_name": "Partner 1",
          "calculated_date": "2016-05-25",
          "properties_matched": 13973,
          "price_coverage_binary_percentage": 80.8583320561735,
          "price_coverage_percentage": 63.8282480875502,
          "bucket_price_coverage": [
            {
              "arrival_date_bucket": "DAY_0_TO_30",
              "length_of_stay_bucket": "LOS_1_TO_7",
              "price_coverage_count": "1684920",
              "price_coverage_percentage": 67.3796487052833
            }
          ]
        }
      ]
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

For more information, see Prices Coverage Report.

Performance stats

When you specify performance_stats as the query_type, the Scorecard API returns a performance_stats object that contains data about your account's performance.

The following shows a sample performance stats response:

{
  "resource": {
    "performance_stats": {
      "avg_ad_position": 1.4749481752247,
      "previous_period_avg_ad_position": 1.5923138463145,
      "booked_total_price_usd": 201524.019459,
      "previous_period_booked_total_price_usd": 114322.92967,
      "clicks": "78090",
      "previous_period_clicks": "61557",
      "conversions": "1411",
      "previous_period_conversions": "1532",
      "impressions": "3026811",
      "previous_period_impressions": "4518509",
      "billing_cost_usd": 24048.139344,
      "previous_period_billing_cost_usd": 30713.24554,
      "eligible_impressions": "18377610",
      "previous_period_eligible_impressions": "16378327",
      "impression_share": 0.2527940,
      "previous_period_impression_share": 0.21472593,
      "click_share": 0.0926026,
      "previous_period_click_share": 0.102625,
      "mobile_clicks": 29479,
      "previous_period_mobile_clicks": 20522,
      "mobile_conversions": 1379,
      "previous_period_mobile_conversions": 2860,
      "mobile_eligible_impressions": 2749016,
      "previous_period_mobile_eligible_impressions": 2782357,
      "mobile_impressions": 2154653,
      "previous_period_mobile_impressions": 948401
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

For more information, see Performance Report with Conversion Metrics.

Opportunity stats

When you specify opportunity_stats as the query_type, the Scorecard API returns an opportunity_stats object that contains details about missed opportunities for your account.

The following shows a sample opportunity stats response:

{
  "resource": {
    "opportunity_stats": {
      "impressions": "3068211",
      "previous_period_impressions": "4585190",
      "eligible_impressions": "3877610",
      "missed_participations": "8248546",
      "previous_period_missed_participations": "8372149",
      "hotel_impressions": "20162174",
      "previous_period_hotel_impressions": "12005431",
      "hotel_clicks": "153906",
      "previous_period_hotel_clicks": "190108",
      "missed_impressions": 5183989,
      "previous_period_missed_impressions": 9210218,
      "missed_participation_no_price": 307193,
      "previous_period_missed_participation_no_price": 659912,
      "missed_participation_no_availability": 2281588,
      "previous_period_missed_participation_no_availability": 1403979,
      "missed_participation_no_pos": 25162,
      "previous_period_missed_participation_no_pos": 27854,
      "missed_participation_blacklisted_hotels": 940,
      "previous_period_missed_participation_blacklisted_hotels": 352,
      "missed_participation_other": 864757,
      "previous_period_missed_participation_other": 581033,
      "missed_impressions_no_bid": 170,
      "previous_period_missed_impressions_no_bid": 49,
      "missed_impressions_spending_cap_reached": 0,
      "previous_period_missed_impressions_spending_cap_reached": 0,
      "missed_impressions_insufficient_bid": 1468765,
      "previous_period_missed_impressions_insufficient_bid": 1105416,
      "missed_impressions_no_taxes_breakdown": 0,
      "previous_period_missed_impressions_no_taxes_breakdown": 0,
      "missed_impressions_other": 1434746,
      "previous_period_missed_impressions_other": 2140930,
      "mobile_hotel_impressions": 3459840,
      "previous_period_mobile_hotel_impressions": 3018368,
      "mobile_missed_participation": 52030,
      "previous_period_mobile_missed_participation": 141853,
      "mobile_eligible_impressions": 2974601,
      "previous_period_mobile_eligible_impressions": 2782357,
      "mobile_impressions": 854365,
      "previous_period_mobile_impressions": 948400,
      "mobile_missed_impressions": 1848246,
      "previous_period_mobile_missed_impressions": 1873755
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

For more information, see Performance Report with Conversion Metrics.

Configuration stats

When you specify configuration_stats as the query_type, the Scorecard API returns a value indicating whether conversion tracking is set up for your account.

The following shows a sample configuration stats response:

{
  "resource": {
    "configuration_stats": {
      "is_conversion_tracking": false
    },
    "etag": "\"42_j836n7N5y309-j42s24sEQw/IRuWdpaUPdpUb42sSXSWsb0742I0\""
  }
}

If the value of is_conversion_tracking is "true", then conversion tracking is successfully set up for your account. A value of "false" indicates that either conversion tracking is not set up for your account, or that conversion tracking is not currently working.

For more information, see Conversion Tracking.

Scorecard API Changes

Changes to v2.0 of the Scorecard API include the following:

  • All results are returned as JSON.
  • The Scorecard API uses the new RESTful syntax.