> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Hotels

> Search Google Hotels for a destination and get hotels with prices, stars, guest ratings and photos.

# Google Hotels

Search hotels the way travelers do on Google, then work with the list as data. Each hotel comes with its name, star class, guest rating and review count, the lowest nightly price for your dates, map coordinates and photos, plus the `id` you pass to Hotel Details and Hotel Prices. Add check-in and check-out dates and a currency to price a real trip, sort by price or rating, and narrow the list with a price range.

```json theme={"dark"}
{
  "query": "hotels in new york",
  "currency": "USD",
  "results_limit": 18
}
```

Provide a destination or hotel search in query. check\_in and check\_out (YYYY-MM-DD, given together, up to 30 nights) price a specific stay; without them prices are for one night from tomorrow. sort\_by accepts relevance, lowest\_price, highest\_rating or most\_reviewed. results\_limit defaults to 18 and accepts integers from 1 to 140. Each hotel costs 0.15 credits.

## Standard Result Fields

Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use `fields` for MCP queries, `_result_fields` for typed tools, or `--result-fields` in the CLI. Declared fields remain present when their value is `null`.

| Field | Type | Nullable | Description |
| - | - | - | - |
| `id` | `string` | Yes | Hotel ID; pass it to Hotel Details or Hotel Prices. |
| `platform` | `string` | No | Platform the result belongs to, such as `instagram` or `linkedin`. |
| `resource` | `string` | No | SocQ resource represented by the result, such as `videos` or `comments`. |
| `type` | `string` | No | Category of the result item, such as `video`, `post`, or `comment`. |
| `url` | `string` | Yes | URL of the hotel on Google Hotels. |
| `published_at` | `string` | Yes | Time the source item was published, in ISO 8601 format when available. |
| `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. |
| `name` | `string` | Yes | Name of the hotel. |
| `text` | `string` | Yes | Description of the hotel (details only). |
| `stars` | `integer` | Yes | Star class of the hotel, from 1 to 5. |
| `rating` | `number` | Yes | Average guest rating from 1 to 5. |
| `reviews_count` | `integer` | Yes | Number of guest reviews. |
| `price` | `object` | Yes | Lowest nightly price for the stay. |
| `price.amount` | `number` | Yes | Price as a number. |
| `price.currency` | `string` | Yes | Three-letter currency code of the price. |
| `price.formatted` | `string` | Yes | Price with its currency code, such as `USD 176`. |
| `check_in` | `string` | Yes | Check-in date the price is for, in YYYY-MM-DD format. |
| `check_out` | `string` | Yes | Check-out date the price is for, in YYYY-MM-DD format. |
| `is_sponsored` | `boolean` | Yes | Whether the listing is a sponsored placement. |
| `address` | `string` | Yes | Street address of the hotel (details only). |
| `phone` | `string` | Yes | Phone number of the hotel (details only). |
| `website` | `string` | Yes | Official website of the hotel (details only). |
| `location` | `object` | Yes | Where the hotel is. |
| `location.name` | `string` | Yes | Neighborhood of the hotel (details only). |
| `location.city` | `string` | Yes | City name. |
| `location.region` | `string` | Yes | Region, state, or province name. |
| `location.country` | `string` | Yes | Country or territory name or code. |
| `location.latitude` | `number` | Yes | Latitude in decimal degrees. |
| `location.longitude` | `number` | Yes | Longitude in decimal degrees. |
| `location_scores` | `object` | Yes | Location ratings from 1 to 5 (details only). |
| `location_scores.overall` | `number` | Yes | Overall location score. |
| `location_scores.things_to_do` | `number` | Yes | Score for nearby attractions and activities. |
| `location_scores.restaurants` | `number` | Yes | Score for nearby restaurants. |
| `location_scores.transit` | `number` | Yes | Score for public transport access. |
| `location_scores.airport_access` | `number` | Yes | Score for access to the airport. |
| `check_in_time` | `string` | Yes | Earliest check-in time, as HH:MM (details only). |
| `check_out_time` | `string` | Yes | Latest check-out time, as HH:MM (details only). |
| `amenities` | `array<string>` | Yes | Amenities the hotel offers, such as `Free Wi-Fi` or `Pool` (details only). |
| `rating_distribution` | `array<object>` | Yes | Share of guest reviews at each star rating (details only). |
| `rating_distribution.stars` | `integer` | Yes | Star rating, from 1 to 5. |
| `rating_distribution.share` | `number` | Yes | Share of reviews with this rating, from 0 to 1. |
| `review_topics` | `array<object>` | Yes | Topics guests mention in reviews, with how they feel about each (details only). |
| `review_topics.name` | `string` | Yes | Topic, such as `Location` or `Breakfast`. |
| `review_topics.positive_count` | `integer` | Yes | Reviews that speak well of the topic. |
| `review_topics.negative_count` | `integer` | Yes | Reviews that speak badly of the topic. |
| `review_topics.mentions_count` | `integer` | Yes | Reviews that mention the topic. |
| `other_reviews` | `array<object>` | Yes | Ratings of the hotel on other review sites (details only). |
| `other_reviews.source` | `string` | Yes | Name of the review site. |
| `other_reviews.url` | `string` | Yes | URL of the hotel's reviews on that site. |
| `other_reviews.rating` | `number` | Yes | Rating on that site, out of 5. |
| `other_reviews.reviews_count` | `integer` | Yes | Number of reviews on that site. |
| `other_reviews.text` | `string` | Yes | Excerpt of a review from that site. |
| `offers` | `array<object>` | Yes | Prices from each booking site for the stay (details only). |
| `offers.seller` | `string` | Yes | Booking site or the hotel itself. |
| `offers.price` | `object` | Yes | Nightly price on that site. |
| `offers.price.amount` | `number` | Yes | Price as a number. |
| `offers.price.currency` | `string` | Yes | Three-letter currency code of the price. |
| `offers.price.formatted` | `string` | Yes | Price with its currency code, such as `USD 176`. |
| `offers.url` | `string` | Yes | Booking link on Google Hotels for that site. |
| `offers.is_official` | `boolean` | Yes | Whether the offer comes from the hotel's own website. |
| `offers.is_sponsored` | `boolean` | Yes | Whether the offer is a sponsored placement. |
| `offers.free_cancellation_until` | `string` | Yes | Time until which the booking can be cancelled for free, when offered. |
| `images` | `array<string>` | Yes | URLs of photos of the hotel. |
| `rank` | `integer` | Yes | Position of the hotel in the search results, starting at 1 (search only). |
| `query` | `string` | Yes | Search the results are for (search only). |

The following example shows the response format for a completed task. Actual data depends on your query.

## Completed Task Response

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "example-google-hotels-search",
    "status": "succeeded",
    "public_id": "google-hotels/search",
    "result_count": 1,
    "credits_amount": 0.15,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "schema_id": "hotel",
      "schema_version": "1.0",
      "items": [
        {
          "id": "ChoIyKbJ6puqvPf8ARoNL2cvMTFqNHR2MjczeBAB",
          "platform": "google-hotels",
          "resource": "search",
          "type": "hotel",
          "url": "https://www.google.com/travel/hotels/entity/ChoIyKbJ6puqvPf8ARoNL2cvMTFqNHR2MjczeBAB",
          "published_at": null,
          "collected_at": "2026-11-17T23:54:33.067544Z",
          "name": "The Rockaway Hotel",
          "text": null,
          "stars": 4,
          "rating": 4.6,
          "reviews_count": 1791,
          "price": {
            "amount": 265,
            "currency": "USD",
            "formatted": "USD 265"
          },
          "check_in": "2026-11-18",
          "check_out": "2026-11-19",
          "is_sponsored": false,
          "address": null,
          "phone": null,
          "website": null,
          "location": {
            "name": null,
            "city": null,
            "region": null,
            "country": null,
            "latitude": 40.5815002,
            "longitude": -73.8300876
          },
          "location_scores": null,
          "check_in_time": null,
          "check_out_time": null,
          "amenities": [],
          "rating_distribution": [],
          "review_topics": [],
          "other_reviews": [],
          "offers": [],
          "images": [
            "https://lh3.googleusercontent.com/grass-cs/AABkmLfo__PIr6n9Zm8EP9Vl8usPu2VfsitYLenrvlQRE3y0W-kJNPC7LAVu6rqk2E6a1DqNEvUB9VVo0QvDeyoKDsJZf6FUtzDj-sKTGR2KmT9OYV6KQ1tm-PictQy9dHYUKEyqW5ZK=s287-w287-h192-n-k-no-v1",
            "https://lh3.googleusercontent.com/grass-cs/AABkmLfOoJ-il_uwZFzkQQdsFJkC5mvJA--sBQ3PW3A6wIaQ5DoS2a-1C225Lmxv3QEx8_UWaCsB-nXWfZ-ztn36i-_X0f-_8Shqz9R4T03KQmRQV6bT7mvSJIEhDypyJwmVOKAW7x7-UA=s287-w287-h192-n-k-no-v1",
            "https://lh3.googleusercontent.com/grass-cs/AABkmLfE6ilDT7zMiXVGqUdhfUV2dhuYyYNyDkbQqRq8Jk0LBO8QpUeLTiX0Dyxzp-gQV3aBX6flm2x3r7gIkn8wh5WcYFjSuCJoQEQAPURGUY-6pxj8mzHY5QWh-KThh3_GMmCNW6nq=s287-w287-h192-n-k-no-v1"
          ],
          "rank": 1,
          "query": "hotels in new york"
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml api-manual/agent-api/agent-api.json POST /v1/google-hotels/search
openapi: 3.1.0
info:
  title: SocQ Agent API
  version: v1-87892a6484c2
  description: Asynchronous social data API generated from the SocQ Capability Registry.
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/google-hotels/search:
    post:
      tags:
        - google-hotels
      summary: Google Hotels API
      description: >-
        Search Google Hotels for a destination, with prices, stars and guest
        ratings.
      operationId: socq_google_hotels_search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              additionalProperties: false
              properties:
                callback_url:
                  type: string
                  format: uri
                check_in:
                  type: string
                  pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
                  description: >-
                    Check-in date in YYYY-MM-DD format. Defaults to tomorrow;
                    give check_out with it.
                check_out:
                  type: string
                  pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
                  description: >-
                    Check-out date in YYYY-MM-DD format, after check_in and at
                    most 30 nights later.
                currency:
                  type: string
                  pattern: ^[A-Za-z]{3}$
                  description: Three-letter currency code for prices, such as USD or EUR.
                language_code:
                  type: string
                  minLength: 2
                  maxLength: 10
                  default: en
                  description: Language code of the results. Defaults to en.
                location_code:
                  type: integer
                  minimum: 1
                  description: >-
                    Search market location code. Defaults to 2840 (United
                    States).
                  default: 2840
                max_price:
                  type: number
                  minimum: 0
                  description: Highest nightly price to include, in the chosen currency.
                min_price:
                  type: number
                  minimum: 0
                  description: Lowest nightly price to include, in the chosen currency.
                query:
                  type: string
                  minLength: 1
                  description: Destination or hotel search, such as `hotels in new york`.
                results_limit:
                  type: integer
                  minimum: 1
                  maximum: 140
                  default: 18
                sort_by:
                  type: string
                  minLength: 1
                  enum:
                    - highest_rating
                    - lowest_price
                    - most_reviewed
                    - relevance
              required:
                - query
              description: >-
                Provide a destination or hotel search in query. Add check_in and
                check_out to price a specific stay; without them prices are for
                one night from tomorrow. results_limit defaults to 18 and
                accepts integers from 1 to 140.
      responses:
        '200':
          description: Task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSubmitResponse'
        '422':
          description: Input validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentValidationErrorResponse'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    AgentSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          const: 200
        data:
          type: object
          properties:
            task_id:
              type: string
            status:
              type: string
            created_time:
              type:
                - string
                - 'null'
          required:
            - task_id
            - status
    AgentValidationErrorResponse:
      type: object
      properties:
        code:
          type: integer
          const: 422
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            details:
              type: object
          required:
            - message
            - type
      required:
        - code
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.