Google Hotel with SerpAPI

Create custom API integrations using OpenAPI schemas to extend Mates' capabilities with any REST service

Last updated 11 months ago

Icon to Download

Overview

I. Introduction

The SerpAPI Google Hotels API tool empowers any Mate to search for comprehensive hotel and vacation rental information worldwide through Google Hotels. This powerful tool provides access to detailed property listings, pricing, amenities, ratings, and more to help users make informed accommodation decisions.

II. Key Features

  • Hotel & Vacation Rental Search: Find accommodations by location, name, or specific criteria

  • Comprehensive Property Details: Access property names, descriptions, images, and GPS coordinates

  • Pricing Information: View nightly rates and total costs for your stay

  • Filtering Capabilities: Refine results by price range, ratings, hotel class, and more

  • Sorting Options: Arrange results by price, rating, or review count

  • Flexible Date Selection: Specify check-in and check-out dates

  • Guest Configuration: Set number of adults, children, and child ages

  • Localization Options: Choose currency, country, and language preferences

III. Usage Instructions

Required Parameters

For every search, you must provide:

  • Search Query (q): Location or hotel name (e.g., "Bali Resorts", "New York Hotels")

  • Check-in Date (check_in_date): Arrival date in YYYY-MM-DD format (e.g., "2025-03-20")

  • Check-out Date (check_out_date): Departure date in YYYY-MM-DD format (e.g., "2025-03-25")

Optional Parameters for Refining Results

  • Guest Configuration:

    • adults: Number of adults (default: 2)

    • children: Number of children (default: 0)

    • children_ages: Ages as comma-separated values (e.g., "5,8,10")

  • Pricing Options:

    • currency: Currency code for prices (default: "USD")

    • min_price: Minimum price filter (e.g., 100)

    • max_price: Maximum price filter (e.g., 500)

  • Quality Filters:

    • rating: Minimum rating filter ("7"=3.5+, "8"=4.0+, "9"=4.5+)

    • hotel_class: Star rating filter (e.g., "4,5" for 4-5 star properties)

  • Sorting and Display:

    • sort_by: Sort criteria ("3"=lowest price, "8"=highest rating, "13"=most reviewed)

    • gl: Google country code (default: "us")

    • hl: Language code (default: "en")

  • Special Options:

    • vacation_rentals: Set to true to search for vacation rentals instead of hotels

    • property_token: Token to retrieve detailed information about a specific property

    • no_cache: Force a fresh search instead of using cached results (default: false)

Example Queries

Basic Hotel Search:

q: "Paris Hotels"
check_in_date: "2025-06-15"
check_out_date: "2025-06-20"

Family Vacation with Filters:

q: "Orlando Resorts"
check_in_date: "2025-07-10"
check_out_date: "2025-07-17"
adults: 2
children: 2
children_ages: "7,10"
hotel_class: "4,5"
max_price: 400

Budget-Friendly Vacation Rental:

q: "Costa Rica Beach"
check_in_date: "2025-02-01"
check_out_date: "2025-02-08"
vacation_rentals: true
sort_by: "3"
max_price: 200

IV. Response Details

The API returns comprehensive information about properties matching your search criteria:

  • Property Details: Name, description, GPS coordinates, property type

  • Pricing Information: Nightly rates and total cost for the stay

  • Quality Indicators: Overall rating (0-5 scale) and number of reviews

  • Visual Content: Property images

  • Amenities: Available facilities and services

  • Property Token: For retrieving more detailed information about specific properties

V. Credentials Configuration

The SerpAPI Google Hotels API requires a SerpAPI key for authentication.

Credentials JSON Structure

{
  "customParameters": {
    "serpApiKey": "YOUR_SERP_API_KEY"
  }
}

Configuration Steps

  1. Obtain an API key from SerpAPI

  2. Navigate to the Tool instance configuration

  3. Locate the "Credentials" section

  4. Replace "YOUR_SERP_API_KEY" with your actual SerpAPI key

  5. Save the configuration

Important Security Information:

  • Your API key is stored securely in a high-security secret manager system

  • For security reasons, the credential JSON cannot be viewed or retrieved after saving

  • If you need to modify the API key, you must completely replace the existing JSON

VI. Best Practices

  • Be Specific: Use detailed location names or hotel names for more precise results

  • Date Format: Always use YYYY-MM-DD format for dates

  • Refine Results: Use optional parameters to narrow down search results

  • Combine Filters: Use multiple filters together for the most relevant results

  • Check Currency: Ensure you've specified the desired currency for consistent pricing

  • Use Property Tokens: When available, use property tokens to retrieve detailed information about specific properties

VII. Limitations

  • Results depend on the data available from Google Hotels via SerpAPI

  • Availability and pricing information may change frequently

  • Some properties may have limited information available

  • Search accuracy depends on the specificity of your query

  • API response times may vary based on search complexity

VIII. Security Considerations

  • The SerpAPI key is stored securely in the All Mates platform's secret manager

  • All communications with the API are encrypted

  • The platform follows best practices for handling sensitive API credentials

  • API usage is monitored to prevent unauthorized access

IX. Conclusion

The SerpAPI Google Hotels API Tool provides a powerful way to search for and compare accommodations worldwide. By leveraging Google Hotels data through SerpAPI, this tool enables Mates to access comprehensive property information, helping users make informed decisions about their accommodations.

Whether planning business travel, family vacations, or personal getaways, this tool offers the flexibility and detailed information needed to find the perfect place to stay.

OpenAPI Schema

openapi: 3.0.3
info:
  title: SerpAPI Google Hotels API
  description: |
    API to search for hotels and vacation rentals through Google Hotels via SerpAPI.
    
    ## For LLMs
    - This API allows searching for hotels or vacation rentals with flexible filtering options
    - IMPORTANT: When you see template variables like '{{serpApiKey}}', you MUST pass them exactly as written
    - Do NOT remove the curly braces or attempt to replace template variables with actual values
    - Template variables will be automatically replaced with real values during execution
  version: 1.0.0
servers:
  - url: https://serpapi.com
paths:
  /search:
    get:
      summary: Search for hotels or vacation rentals
      description: |
        Retrieves hotel or vacation rental listings based on search parameters.
        
        ## For LLMs
        - Use this endpoint to find hotels or vacation rentals in a specific location
        - Required parameters: engine, api_key, q, check_in_date, check_out_date
        - For vacation rentals instead of hotels, set vacation_rentals=true
        - Sort options: "3" (lowest price), "8" (highest rating), "13" (most reviewed)
        - Filter by price range using min_price and max_price
        - Filter by rating: "7" (3.5+), "8" (4.0+), "9" (4.5+)
      operationId: searchHotels
      parameters:
        - name: engine
          in: query
          description: Search engine to use (must be "google_hotels").
          required: true
          schema:
            type: string
            enum: ["google_hotels"]
            default: "google_hotels"
        - name: api_key
          in: query
          description: |
            SerpAPI key for authentication.
            
            ## For LLMs
            - IMPORTANT: You MUST use the EXACT string '{{serpApiKey}}' including the curly braces
            - Do NOT remove the curly braces or modify this template string
            - This template will be automatically replaced during tool execution
          required: true
          schema:
            type: string
            enum: ['{{serpApiKey}}']
          example: '{{serpApiKey}}'
        - name: q
          in: query
          description: |
            Search query (location, hotel name, etc.).
            
            ## For LLMs
            - For best results, provide specific location names
            - Can include city names, regions, or specific hotel names
            - Examples: "Paris hotels", "Bali resorts", "New York luxury hotels"
          required: true
          schema:
            type: string
          example: "Bali Resorts"
        - name: check_in_date
          in: query
          description: |
            Check-in date in YYYY-MM-DD format.
            
            ## For LLMs
            - Must be a valid date in YYYY-MM-DD format
            - Date must be in the future
          required: true
          schema:
            type: string
            format: date
          example: "2025-03-20"
        - name: check_out_date
          in: query
          description: |
            Check-out date in YYYY-MM-DD format.
            
            ## For LLMs
            - Must be a valid date in YYYY-MM-DD format
            - Must be after the check_in_date
          required: true
          schema:
            type: string
            format: date
          example: "2025-03-25"
        - name: adults
          in: query
          description: Number of adults staying.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 2
          example: 2
        - name: children
          in: query
          description: |
            Number of children staying.
            
            ## For LLMs
            - If children > 0, consider providing children_ages parameter
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
        - name: children_ages
          in: query
          description: |
            Ages of children (comma-separated).
            
            ## For LLMs
            - Only needed when children parameter > 0
            - Format: comma-separated list of ages
            - Example: "5,8,10" for three children aged 5, 8, and 10
          required: false
          schema:
            type: string
          example: "5,8,10"
        - name: currency
          in: query
          description: Currency code for prices (ISO 4217).
          required: false
          schema:
            type: string
            default: "USD"
          example: "USD"
        - name: gl
          in: query
          description: Google country code (affects search results localization).
          required: false
          schema:
            type: string
            default: "us"
          example: "us"
        - name: hl
          in: query
          description: Language code for results.
          required: false
          schema:
            type: string
            default: "en"
          example: "en"
        - name: sort_by
          in: query
          description: |
            Sort results by criteria.
            
            ## For LLMs
            - "3": Sort by lowest price
            - "8": Sort by highest rating
            - "13": Sort by most reviewed
          required: false
          schema:
            type: string
            enum: ["3", "8", "13"]
          example: "3"
        - name: min_price
          in: query
          description: Minimum price filter (in the specified currency).
          required: false
          schema:
            type: integer
            minimum: 0
          example: 100
        - name: max_price
          in: query
          description: Maximum price filter (in the specified currency).
          required: false
          schema:
            type: integer
            minimum: 0
          example: 500
        - name: rating
          in: query
          description: |
            Filter by minimum rating.
            
            ## For LLMs
            - "7": Hotels rated 3.5 stars and above
            - "8": Hotels rated 4.0 stars and above
            - "9": Hotels rated 4.5 stars and above
          required: false
          schema:
            type: string
            enum: ["7", "8", "9"]
          example: "8"
        - name: hotel_class
          in: query
          description: |
            Filter by hotel class (star rating).
            
            ## For LLMs
            - Format: comma-separated list of star ratings
            - Example: "4,5" for 4 and 5-star hotels only
          required: false
          schema:
            type: string
          example: "4,5"
        - name: vacation_rentals
          in: query
          description: |
            Search for vacation rentals instead of hotels.
            
            ## For LLMs
            - Set to true to search for vacation rentals
            - Set to false or omit to search for hotels
          required: false
          schema:
            type: boolean
          example: false
        - name: property_token
          in: query
          description: |
            Token to retrieve detailed information about a specific property.
            
            ## For LLMs
            - Use this to get detailed information about a specific property
            - This token is available in the property_token field of each property in search results
            - When using this parameter, most other parameters are ignored
          required: false
          schema:
            type: string
        - name: no_cache
          in: query
          description: Force a fresh search instead of using cached results.
          required: false
          schema:
            type: boolean
            default: false
          example: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSearchResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    HotelSearchResponse:
      type: object
      description: |
        Response containing hotel or vacation rental search results.
        
        ## For LLMs
        - The main data is in the "properties" array
        - Each property contains details about a hotel or vacation rental
        - Use search_metadata and search_parameters to understand the search context
        - serpapi_pagination contains info for paginating through results
      properties:
        search_metadata:
          type: object
          description: Metadata about the search request (id, status, created/processed timestamps).
        search_parameters:
          type: object
          description: Parameters used for this search (reflects the query parameters).
        search_information:
          type: object
          description: Information about the search results (total results, displayed results).
        properties:
          type: array
          description: List of hotel or vacation rental properties matching the search criteria.
          items:
            $ref: '#/components/schemas/Property'
        serpapi_pagination:
          type: object
          description: Pagination information for retrieving more results.
    
    Property:
      type: object
      description: |
        Information about a hotel or vacation rental property.
        
        ## For LLMs
        - Contains comprehensive details about a single property
        - price information is in rate_per_night and total_rate
        - Use property_token to get more detailed information about this property
      properties:
        type:
          type: string
          description: Type of property (hotel or vacation rental).
          example: "hotel"
        name:
          type: string
          description: Name of the property.
          example: "Four Seasons Resort Bali at Sayan"
        description:
          type: string
          description: Brief description of the property.
          example: "Luxury resort in Ubud with 2 outdoor pools"
        gps_coordinates:
          type: object
          description: GPS coordinates of the property.
          properties:
            latitude:
              type: number
              example: -8.5069
            longitude:
              type: number
              example: 115.2624
        rate_per_night:
          type: object
          description: Price rates per night.
          properties:
            currency:
              type: string
              example: "USD"
            amount:
              type: number
              example: 450
            display:
              type: string
              example: "$450"
        total_rate:
          type: object
          description: Total price for the entire stay.
          properties:
            currency:
              type: string
              example: "USD"
            amount:
              type: number
              example: 2250
            display:
              type: string
              example: "$2,250"
        images:
          type: array
          description: Property images.
          items:
            type: object
            properties:
              thumbnail:
                type: string
                example: "https://lh3.googleusercontent.com/p/AF1QipNRT..."
              original:
                type: string
                example: "https://lh3.googleusercontent.com/p/AF1QipNRT..."
        overall_rating:
          type: number
          description: Overall rating of the property (0-5 scale).
          example: 4.8
        reviews:
          type: integer
          description: Number of reviews for the property.
          example: 1250
        amenities:
          type: array
          description: Available amenities at the property.
          items:
            type: string
          example: ["Free WiFi", "Pool", "Spa", "Restaurant"]
        property_token:
          type: string
          description: |
            Token for retrieving detailed property information.
            
            ## For LLMs
            - Use this token with the property_token parameter to get detailed information about this property
          example: "ChdDSUhNMG9nS0VJQ0FnSURZdGRtWnFRRUVTQUI"
    
    ErrorResponse:
      type: object
      description: |
        Error response for failed requests.
        
        ## For LLMs
        - Check the error message for details about why the request failed
        - Common errors include invalid API key, missing required parameters, or invalid date formats
      properties:
        error:
          type: string
          description: Error message explaining the failure reason.
          example: "Missing required parameter: check_in_date"