> ## Documentation Index > Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt > Use this file to discover all available pages before exploring further. # Google hotels API > Search Google Hotels with prices, ratings and Google's own filters. Call the Google hotels API for JSON. 1 credit per call. Searches Google Hotels with prices, ratings and Google's own filters. ## Request `query` is required. ```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} import { Stophy } from "stophy"; const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY }); const result = await stophy.google.hotels({ query: "Lisbon", checkIn: "2026-11-19" }); console.log(result.data.results); ``` ```python Python icon="python" theme={null} theme={null} from stophy import Stophy stophy = Stophy() # reads STOPHY_API_KEY result = stophy.google.hotels(query="Lisbon", check_in="2026-11-19") print(result["data"]["results"]) ``` ```bash cURL icon="terminal" theme={null} theme={null} curl -X POST https://api.stophy.dev/v1/google/hotels \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "content-type: application/json" \ -d '{"query":"Lisbon","checkIn":"2026-11-19"}' ``` ```bash CLI icon="square-terminal" theme={null} theme={null} stophy google hotels Lisbon --checkIn 2026-11-19 ``` ## Response If successful, the response body contains the standard envelope. `data.results[]` contains the hotels, each with its price per night, total price, rating and amenities. The following example is a real response, truncated: each list shows one item and long strings are cut. ```json theme={null} { "success": true, "data": { "checkIn": "2026-11-19", "checkOut": "2026-11-20", "results": [ { "name": "Santa Luzia BB - HOrigem - Double Room, River View", "hotelId": "ChkQicjQ0reM7_U9Gg0vZy8xMXo0Y25fNDlzEAI", "hotelUrl": "https://www.google.com/travel/hotels/entity/ChkQicjQ0reM7_U9Gg0vZy8xMXo0Y25fNDlzEAI?hl=en&gl=us&curr=USD&ts=CAESCgoCCAM…", "price": 76, "totalPrice": 80, "priceCurrency": "USD", "rating": 5, "reviews": 8, "amenities": ["Sleeps 2", "7 bedrooms"], "position": 1 } ], "page": 1 }, "creditsUsed": 1, "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b" } ``` | Field | Type | Description | | - | - | - | | `price` | number | The minimum price per night. | | `totalPrice` | number | For the whole stay, with taxes and fees. | | `page` | integer | The page number of this response. | | `position` | integer | The 1-based position of the result in the list. | | `rating` | number | The average star rating, on a scale of 1 to 5. | | `reviews` | integer | The number of reviews the rating is based on. | For every field, see the response schema on this page. ## Optional parameters | Parameter | Type | Description | | - | - | - | | `checkIn` | string (date) | The check-in date. Defaults to tomorrow. Format: `YYYY-MM-DD`. | | `checkOut` | string (date) | The check-out date. Defaults to one night after `checkIn`. Format: `YYYY-MM-DD`. | | `adults` | integer | The number of adults. Must be between 1 and 12. If unset, defaults to `2`. | | `childrenAges` | integer\[] | One age for each child, such as `[7, 12]`. Accepts up to 8 values. | | `currency` | string | Three-letter currency code, such as `USD`. If unset, defaults to `USD`. | | `minPrice` | integer | The minimum price per night. | | `maxPrice` | integer | The maximum price per night. | | `minRating` | string | Restricts results to hotels with at least this guest rating. Acceptable values are `3.5+`, `4+` and `4.5+`. | | `hotelClass` | integer\[] | Restricts results to hotels with these star ratings, such as `[4, 5]`. Accepts up to 4 values. | | `amenities` | string\[] | Restricts results to hotels that offer every one of these. Accepts one of 19 values, such as `freeWifi`, `freeBreakfast` and `restaurant`. | | `propertyTypes` | string\[] | Restricts results to these kinds of property. Acceptable values are `beachHotels`, `boutiqueHotels`, `hostels`, `inns`, `motels`, `resorts`, `spaHotels`, `bedAndBreakfasts`, `other` and `apartmentHotels`. | | `freeCancellation` | boolean | Restricts results to hotels that offer free cancellation. If unset, defaults to `false`. | | `specialOffers` | boolean | Restricts results to hotels with special offers. If unset, defaults to `false`. | | `sort` | string | Specifies the order of the hotels. Acceptable values are `relevance`, `lowestPrice`, `highestRating` and `mostReviewed`. If unset, defaults to `relevance`. | | `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 10. If unset, defaults to `1`. | ## Billing Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed. ## Pagination Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 10. ## Related methods * [Tripadvisor search](/api-reference/endpoint/tripadvisor-search): Accepts a hotel's `name` as `query`. Searches hotels, restaurants and attractions. ## OpenAPI ````yaml api-reference/openapi.json POST /v1/google/hotels openapi: 3.1.0 info: title: Stophy API version: '1' description: >- Every endpoint is a POST that takes its input as a JSON object body. Unknown fields are rejected with 400. Responses leave out empty values: null, empty strings, empty objects and empty nested lists are not sent. x-credits is what one call costs. Every call costs the same, whatever it returns, unless an operation's description says it costs per 10 results, or per second of audio. Then x-credits is the lowest price and x-credits-max the most one call can cost. Where an operation takes limit, send it to return fewer results and pay for fewer. When a response has a cursor, send it back unchanged with the same input to get the next page. When it has a page, send the next page number. servers: - url: https://api.stophy.dev security: - apiKey: [] paths: /v1/google/hotels: post: summary: Search Google Hotels with prices, ratings and Google's own filters description: Costs 1 credit per call. Pages with page. operationId: googleHotels requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 200 description: Where to stay, like Zanzibar or hotels near Times Square. checkIn: description: Defaults to tomorrow. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ checkOut: description: Defaults to one night after checkIn. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ adults: default: 2 type: integer minimum: 1 maximum: 12 childrenAges: default: [] description: One age per child, like [7, 12]. maxItems: 8 type: array items: type: integer minimum: 0 maximum: 17 currency: default: USD type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code, e.g. USD. minPrice: description: Per night. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 maxPrice: description: Per night. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 minRating: description: Google Hotels' own Guest rating. type: string enum: - 3.5+ - 4+ - 4.5+ hotelClass: default: [] description: Google Hotels' own Hotel class, as star counts like [4, 5]. maxItems: 4 type: array items: type: integer minimum: 2 maximum: 5 amenities: default: [] description: Google Hotels' own Amenities. Every one must be offered. type: array items: type: string enum: - freeWifi - freeBreakfast - restaurant - bar - kidFriendly - petFriendly - freeParking - parking - evCharger - roomService - fitnessCenter - spa - pool - indoorPool - outdoorPool - airConditioned - wheelchairAccessible - beachAccess - allInclusiveAvailable propertyTypes: default: [] description: Google Hotels' own Property type. type: array items: type: string enum: - beachHotels - boutiqueHotels - hostels - inns - motels - resorts - spaHotels - bedAndBreakfasts - other - apartmentHotels freeCancellation: default: false type: boolean specialOffers: default: false type: boolean sort: default: relevance type: string enum: - relevance - lowestPrice - highestRating - mostReviewed page: default: 1 description: Page number, starting at 1. type: integer minimum: 1 maximum: 10 required: - query additionalProperties: false example: query: Lisbon checkIn: '2026-11-19' responses: '200': description: The data, and the credits this call used. headers: X-Request-ID: $ref: '#/components/headers/RequestId' x-credits-used: $ref: '#/components/headers/CreditsUsed' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' x-cache: $ref: '#/components/headers/Cache' x-cache-age: $ref: '#/components/headers/CacheAge' content: application/json: schema: type: object required: - success - data - creditsUsed - requestId properties: success: const: true data: type: object additionalProperties: false properties: checkIn: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ checkOut: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ results: type: array items: type: object additionalProperties: false properties: name: type: string minLength: 1 hotelId: type: string minLength: 1 hotelUrl: type: string format: uri price: description: Lowest price per night. type: number minimum: 0 totalPrice: description: For the whole stay, with taxes and fees. type: number minimum: 0 priceCurrency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code, e.g. USD. deal: description: Google's badge, like DEAL or GREAT DEAL. type: string dealDescription: description: Like 20% less than usual. type: string rating: type: number minimum: 0 maximum: 5 reviews: type: integer minimum: 0 maximum: 9007199254740991 hotelClass: type: integer minimum: 1 maximum: 5 amenities: type: array items: type: string minLength: 1 position: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - name - hotelId - hotelUrl - position page: type: integer minimum: 1 maximum: 9007199254740991 required: - checkIn - checkOut - results - page creditsUsed: type: integer requestId: type: string 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' components: headers: RequestId: description: The request id. Quote it when you report a problem. schema: type: string CreditsUsed: description: Credits this call used. schema: type: integer RateLimitLimit: description: Requests allowed in the current window. schema: type: integer RateLimitRemaining: description: Requests left in the current window. schema: type: integer RateLimitReset: description: Unix time in seconds when the current window resets. schema: type: integer Cache: description: hit if this result came from the cache, miss if it was fetched live. schema: type: string CacheAge: description: Seconds since the returned result was written to the cache. schema: type: integer RetryAfter: description: Seconds to wait before retrying. schema: type: integer responses: Error: description: The request failed. retryable says whether trying again can help. headers: X-Request-ID: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - success - error properties: success: const: false error: type: object required: - code - message - retryable - requestId properties: code: type: string enum: - cliSessionCompleted - cliSessionExists - cliSessionNotFound - forbidden - insufficientCredits - internalError - inviteClaimed - inviteDisabled - inviteExpired - inviteUsedUp - invalidCliSession - invalidCliVerifier - invalidRequest - notFound - rateLimited - sourceChanged - sourceRefused - sourceTimeout - sourceUnavailable - tooManyInFlight - unauthorized - unsupportedMediaType message: type: string retryable: type: boolean retryAfterSeconds: type: integer requestId: type: string requiredCredits: type: number availableCredits: type: number billingUrl: type: string const: https://stophy.dev/billing securitySchemes: apiKey: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.