Skip to content

Google Hotels

Overview

Method Endpoint Version Description
POST /api/v1/open/search v1 Google Search API endpoint for retrieving search results

Request Headers

Header Type Required Description
Content-Type string Yes Must be set to application/json
Accept string No Response format (defaults to application/json)

Authentication

API Key Authentication - Pass the API key as a request parameter: api_key=your_api_key - Example: "api_key": "your_api_key_here"

Request Example

curl -X POST "https://domain/api/v1/open/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    // ...
  }'

Response Format

All responses follow a standardized JSON structure:

{
  "code": 200,
  "msg": "Success",
  "reqId": "req_1234567890",
  "timestamp": "2025-01-08T10:30:00Z",
  "data": {
    // Response data object
  }
}

HTTP Status Codes

Code Status Description Retry
200 OK Request successful No

Request Parameters

Parameter Type Required Description Default
api_key string Yes API key for authentication
engine string Yes Search engine type, currently engine value is google_hotels google
q string Yes Search query, supports regular Google search syntax (like inurl:, site:, intitle:) and advanced search parameters
gl string No Search country code (e.g., us-United States, uk-United Kingdom, fr-France). Head to the Google countries page for a full list of supported Google countries.
hl string No Search language code (e.g., en-English, es-Spanish, fr-French). Head to the Google languages page for a full list of supported Google languages.
currency string No Parameter defines the currency of the returned prices. Default to USD. Head to the Google Travel Currencies page for a full list of supported currency codes.
check_in_date string No Parameter defines the check-in date. The format is YYYY-MM-DD. e.g. 2025-07-26
check_out_date string No Parameter defines the check-out date. The format is YYYY-MM-DD. e.g. 2025-07-27
adults string No Parameter defines the number of adults. Default to 2. 2
children string No Parameter defines the number of children. Default to 0. 0
children_ages string No Parameter defines the ages of children. The age range is from 1 to 17, with children who haven't reached 1 year old being considered as 1. Example for single child only: 5 Example for multiple children (seperated by comma ,): 5,8,10 The number of children's ages specified must match the children. 0
sort_by string No Parameter is used for sorting the results. Default is sort by Relevance. Available options: 3 - Lowest price, 8 - Highest rating, 13 - Most reviewed
min_price string No Parameter defines the lower bound of price range.
max_price string No Parameter defines the upper bound of price range.
property_types string No Parameter defines to include only certain type of property in the results. Head to the Google Hotels Property Types page for a full list of supported Hotels property types. For Vacation Rentals, please refer to the Google Vacation Rentals Property Types page for a full list of supported Vacation Rentals property types. Example for single property type only: 17 Example for multiple property types (seperated by comma ,): 17,12,18
amenities string No Parameter defines to include only results that offer specified amenities. Head to the Google Hotels Amenities page for a full list of supported Hotels amenities. For Vacation Rentals, please refer to the Google Vacation Rentals Amenities page for a full list of supported Vacation Rentals amenities. Example for single amenity only: 35 Example for multiple amenities (seperated by comma ,): 35,9,19
rating string No Parameter is used for filtering the results to certain rating. Available options: 7 - 3.5+, 8 - 4.0+, 9 - 4.5+
brands string No Parameter defines the brands where you want your search to be concentrated. ID values are accessible inside brands array, located in our JSON output (e.g. brands[0].id). Example for single brand only: 33 Example for multiple brands (seperated by comma ,): 33,67,101 This parameter isn't available for Vacation Rentals.
hotel_class string No Parameter defines to include only certain hotel class in the results. Available options: 2 - 2-star, 3 - 3-star, 4 - 4-star, 5 - 5-star. Example for single hotel class only: 2 Example for multiple hotel class (seperated by comma ,): 2,3,4 This parameter isn't available for Vacation Rentals.
free_cancellation string No Parameter defines to show results that offer free cancellation. This parameter isn't available for Vacation Rentals.
special_offers string No Parameter defines to show results that have special offers. This parameter isn't available for Vacation Rentals.
eco_certified string No Parameter defines to show results that are eco certified. This parameter isn't available for Vacation Rentals.
vacation_rentals string No Parameter defines to search for Vacation Rentals results. Default search is for Hotels.
bedrooms string No Parameter defines the minimum number of bedrooms. Default to 0. This parameter only available for Vacation Rentals. 0
bathrooms string No Parameter defines the minimum number of bathrooms. Default to 0. This parameter only available for Vacation Rentals. 0
next_page_token string No Parameter defines the next page token. It is used for retrieving the next page results. 0
property_token string No Parameter is used to get property details which consists of name, address, phone, prices, nearby places, and etc. You can find property_token from Google Hotels Properties API. 0
html string No Whether to return HTML format, 1-yes, 0-no 0

Response Example

{
  "reqId": "1984168106343272448",
  "code": 200,
  "msg": "OK",
  "data": {
    "search_metadata": {
      "raw_html_file": "oss_html",
      "total_time_taken": 2.068001541,
      "id": "1984168106343272448",
      "json_endpoint": "oss_json",
      "created_at": "2025-10-31 15:58:35",
      "processed_at": "2025-10-31 15:58:39",
      "google_url": "https://www.google.com/travel/search?q=Bali Resorts",
      "status": "Success"
    },
    "search_information": {
      "time_taken_displayed": 0.076,
      "total_results": "188"
    },
    "search_parameters": {
      "engine": "google_hotels",
      "html": "0",
      "google_domain": "www.google.com",
      "q": "Bali Resorts"
    },
    "brands": [
        {
            "id": 262,
            "name": "Unbound Collection"
        }
    ],
    "ads": [
        {
            "name": "The Lalu Nanjing",
            "source": "The Lalu Nanjing",
            "source_icon": "//www.gstatic.com/travel-hotels/branding/icon_default.png",
            "link": "https://www.google.com/aclk?sa=l&ai=DChsSEwiQ36-zlqiQAxXF1RYFHHa2FEgoYACICCAEQBRoCdGw&co=1&gclid=EAIalQobChMIkN-vs5aokAMVxdUWBR2thRIKEAOYASABEgJPrvD_BwE&cid=CAASNuRo4gS0n49B0SuqXafY7V_8uL1mCnA_CrQUNNi6d2BBIQZFAt_eoMYh_0MjD08-8HvgW4PQ&sig=AOD64_1zUBykEoPdOyM8sMequERRiWS-5Q&adurl",
            "property_token": "Cgolk5vexb696VEEAE",
            "gps_coordinates": {
                "latitude": 32.039425,
                "longitude": 118.72251999999999
            },
            "hotel_class": 3,
            "thumbnail": "https://lh3.googleusercontent.com/proxy/eVCyDk-wWjbfNoUYVx_LtWlV_OxaCPjeBNUb1qO7-mAEA5nSWdR9aztm1TKH_bj7_4E-k3XqBwAREC9s-1VZht3Av9c-sciJnaMKJW2ZlcxZh8_z7qBL-4QjzkAS7clqNdzJM-scxgXl2gweTvslg0rNdf7jDvg=w254-h150-k-no",
            "overall_rating": 4,
            "reviews": 13,
            "price": "THB 8,906",
            "extracted_price": "THB 8,906",
            "amenities": [
                "Free cancellation",
                "Pool"
            ],
            "free_cancellation": true
        }
    ],
    "properties": [
      {
          "type": "hotel",
          "name": "Suning Universal Hotel",
          "property_token": "Chgl7KvesNyUt5_UARoLL2cvMXRkeWNwOTYQAQ",
          "gps_coordinates": {
              "latitude": 32.0510413,
              "longitude": 118.77443419999999
          },
          "check_in_time": "2:00 PM",
          "check_out_time": "12:00 PM",
          "rate_per_night": {
              "before_taxes_fees": "THB 1,471",
              "extracted_before_taxes_fees": "THB 1,471"
          },
          "total_rate": {
              "before_taxes_fees": "THB 1,471",
              "extracted_before_taxes_fees": "THB 1,471"
          },
          "prices": [
              {
                  "logo": "https://www.gstatic.com/images/branding/product/1x/googleg_48dp.png",
                  "rate_per_night": {
                      "before_taxes_fees": "THB 1,471",
                      "extracted_before_taxes_fees": "THB 1,471"
                  },
                  "num_guests": 2
              }
          ],
          "nearby_places": [
              {
                  "name": "Nanjing Lukou International Airport",
                  "transportations": [
                      {
                          "duration": "55 min"
                      }
                  ]
              }
          ],
          "hotel_class": "5-star hotel",
          "extracted_hotel_class": 5,
          "images": [
            {
              "original_image": "https://lh3.googleusercontent.com/p/AF1QipMOjoiT-37C4bKT3hog7qKf-bihAEJnaIIV7tJd",
              "thumbnail": "https://lh3.googleusercontent.com/p/AF1QipMOjoiT-37C4bKT3hog7qKf-bihAEJnaIIV7tJd=s287-w287-h192-n-k-no-v1"
            }
          ],
          "overall_rating": 3.4,
          "reviews": 7,
          "ratings": [
              {
                  "stars": 5,
                  "count": 1
              }
          ],
          "location_rating": "4.2",
          "amenities": [
              "Breakfast",
              "Free Wi-Fi",
              "Free parking",
              "Indoor pool",
              "Air conditioning",
              "Fitness center",
              "Restaurant",
              "Room service"
          ]
      }
    ]
  }
}

Complete Response Parameters Overview

search_metadata

object Contains metadata about the search execution

Parameter Type Description Applicable Terminal
id string Unique identifier for the search request desktop
json_endpoint string Provide an interface endpoint for searching related JSON data, through which JSON-formatted search data can be obtained desktop
created_at string The timestamp when the search request was created, recording the time when the search was initiated desktop
processed_at string The timestamp when the search results were processed and became available for return, recording the time point from processing to completion of the search desktop
google_url string The Google search URL, which contains the search keyword "coffee" along with language parameters (hl=en for English), regional parameters (gl=us for the United States), and other search parameters, used to redirect to the corresponding Google search page desktop
status string Status of the search execution (e.g., Success) desktop
raw_html_file string Identifier for the original HTML file desktop
total_time_taken number The total time spent on the entire search process (including request sending, result parsing, and other stages) desktop

search_information

object Contains information about the search results

Parameter Type Description Applicable Terminal
time_taken_displayed number TDisplay time (i.e., the time spent on displaying the search results) desktop
total_results string Total results count (the total number of results returned by this search) desktop

search_parameters

object Contains the parameters used for the search

Parameter Type Description Applicable Terminal
q string Keywords used for this query desktop
engine string Search engine used for this query (e.g., google_web) desktop
google_domain string Specifies the corresponding Google domain (e.g., google.com, etc., used to distinguish Google services in different regions/locales) desktop
device string Device type used during search (e.g., desktop) desktop
html string When HTML=0, returns JSON; when HTML=1, returns HTML; when HTML=2, returns both JSON and HTML desktop

brands

object[] Hotel brands, used to categorize and display different hotel chains.

Parameter Type Description Applicable Terminal
id string Unique identifier ID for hotel brand desktop
name string Name of the hotel brand desktop

ads

object[] Hotel-related advertisements, including promotional and marketing ads for hotel brands or individual hotels.

Parameter Type Description Applicable Terminal
name string Name of the hotel (advertisement), used to identify a specific hotel desktop
source string Source name of the hotel (advertisement) desktop
source_icon string Source logo URL (image address of the brand identifier for the content origin, typically in data:image/png;base64 format) desktop
link string Redirect link for hotel advertisement, leading to hotel details or booking-related pages desktop
property_token string Unique identifier token for hotel property, used to distinguish different properties within the system desktop
gps_coordinates object Object encapsulating hotel GPS coordinate information desktop
gps_coordinates.latitude number Latitude value of the hotel's location desktop
gps_coordinates.longitude number Longitude value of the hotel's location desktop
hotel_class number Hotel rating desktop
thumbnail string Thumbnail URL of the hotel, used to display related images such as exterior and interior views desktop
overall_rating number Overall rating of the hotel, reflecting users' comprehensive evaluation desktop
reviews number Number of hotel reviews desktop
price string Hotel price desktop
extracted_price string Extracted pure price value desktop
amenities string[] List of amenities and services provided by the hotel desktop
free_cancellation boolean Is free cancellation supported desktop

properties

object[] Bookable hotel entity with core details such as location, amenities, and room types

Parameter Type Description Applicable Terminal
type string Property type, such as "hotel" desktop
name string Hotel name desktop
property_token string Unique identifier token for hotel properties, used to distinguish different hotels within the system desktop
gps_coordinates object Encapsulate hotel latitude and longitude information desktop
gps_coordinates.latitude number Latitude value of the hotel's location desktop
gps_coordinates.longitude number Longitude value of the hotel's location desktop
check_in_time string Check-in time desktop
check_out_time string Check-out time desktop
rate_per_night object Encapsulate information related to the nightly rate desktop
rate_per_night.before_taxes_fees string Pre-tax nightly price desktop
rate_per_night.extracted_before_taxes_fees string Extracted core nightly price desktop
total_rate object Encapsulate information related to the total price desktop
total_rate.before_taxes_fees string Total pre-tax price desktop
total_rate.before_taxes_fees string Extracted core total price desktop
prices object[] Price list for different channels/plans desktop
prices[].logo string Price list for different channels/plans desktop
prices[].rate_per_night string Nightly price information under a specific channel desktop
prices[].rate_per_night.before_taxes_fees string Channel-based nightly rate before tax (with formatting) desktop
prices[].rate_per_night.extracted_before_taxes_fees string Extracted core nightly price under channel desktop
prices[].num_guests number Number of guests accommodated by the pricing plan desktop
nearby_places object[] Important places around the hotel desktop
nearby_places[].name string Name of nearby place desktop
nearby_places[].transportations object[] List of transportation duration and related information to the place desktop
hotel_class string Hotel rating description desktop
extracted_hotel_class number Extracted grade value from hotel_class desktop
images object[] Hotel image collection desktop
overall_rating number Overall hotel rating desktop
reviews number Total number of hotel reviews desktop
ratings object[] Distribution list of ratings by star level desktop
ratings[].stars number Specific star rating desktop
ratings[].count number Number of reviews for this star rating desktop
location_rating string Location star rating desktop
amenities string[] List of hotel facilities and services provided desktop