Hotels API v1.2

The Hotels API gives you programmatic access to your Hotel List Feed. You can list all valid hotels, or list hotels that are not indexed. Properties are not indexed when they are unmatched, overclustered, have data quality issues. This can occur if your Hotel List Feed contains one or more of the following issues:

  • Duplicate entries with different IDs
  • Invalid characters or values that are too long or too short
  • Ambiguous or invalid name, address, phone, or geocoding information
  • Two or more hotel listings that are too similar
  • Could not be matched against Google's list of known hotels (Google's manifest)

If you discover that your Hotel List Feed contains issues, remove, fix, or consolidate listings that are causing those issues, and then resubmit the feed. For more information, see Fixing Overclustering, Indexing, and Data Issues.

Hotels API requests

Endpoint: /hotels

Parameters:

Element Required? Description
alt Optional Indicates the desired result format. Valid values are:
  • "json": Indicates a request for JSON results. This is the default.
  • "csv": Indicates a request for a comma separated value (CSV) file.
partner Optional Identifies the technical name of the account that you are requesting data for. The value of this parameter is not the same as the partner name in the Hotel Ads Center or the partner ID (which is a number). If you do not know the technical name, contact us to request it.
type Optional Indicates the type of results you want. Valid values are:
  • "ALL": Requests all of your hotels that are in Google’s hotel manifest. This is the default value.
  • "OVER_CLUSTERED": Requests overclustered hotels only.
  • "LISTING_FEED": Returns a list of all hotels in your Hotel List Feed, including those that have errors that prevent them from inclusion in Google’s hotels manifest. The response also includes the error codes. For a detailed description of the error messages and potential resolutions, see Data Issues Error Messages.

The following example request gets all of your hotels that are in Google's hotel manifest:

https://www.googleapis.com/travelpartner/v1.2/hotels?type=ALL

The following example request gets all hotels that you submitted in your Hotel List Feed, including those that have errors:

https://www.googleapis.com/travelpartner/v1.2/hotels?type=LISTING_FEED

The following example request gets overclustered hotels only:

https://www.googleapis.com/travelpartner/v1.2/hotels?type=OVER_CLUSTERED

Hotels API responses

The Hotels API returns a list of hotels as objects in the hotel_mapping array. Each object in the array represents one of the hotels in the Hotel List Feed.

The following table describes the fields of the objects:

Field Description
kind The type of object. The value is "travelpartner#hotel".
partnerHotelId The unique ID of the hotel as given in your Hotel List Feed.
googleClusterId The Google Maps identifier for the hotel.
dataIssues Indicates that the hotel has data quality issues. The value of this field is an array of error codes that indicate what types of issues the listing has. For more information, see Data Issues Error Messages.
overClusteredPartnerHotelIds Indicates that the hotel is overclustered. The value of this field is the hotel ID. If your feed contains overclustered hotels, update the feed and resubmit it. To do this, you can use the Manual Match Fix tool.

The following example response includes hotels with no data issues, hotels with data issues, and overclustered hotels:

{
  "kind": "travelpartner#hotelList",
  "hotel_mapping": [
    {
      "kind": "travelpartner#hotel",
      "partnerHotelId": "0338",
      "googleClusterId": "1"
    },
    {
      "kind": "travelpartner#hotel",
      "partnerHotelId": "1677",
      "googleClusterId": "2",
      "dataIssues": [
        "MISSING_PHONE_NUMBER"
      ]
    },
    {
      "kind": "travelpartner#hotel",
      "partnerHotelId": "2770",
      "googleClusterId": "3",
      "dataIssues": [
        "MISSING_PHONE_NUMBER",
        "MISSING_ADDRESS"
      ]
    },
    {
      "kind": "travelpartner#hotel",
      "partnerHotelId": "ZQNHQ",
      "googleClusterId": "4",
      "overClusteredPartnerHotelIds": [
        "ZQNAL"
      ]
    }
  ]
}

Hotels API changes

The lintIssues array of error codes was removed from version 1.2. They were deprecated in version 1.1 (sunsetted).