openapi: 3.0.0 info: title: Google Hotels Price Calendar API description: | The Google Hotels Price Calendar API returns the nightly price of a hotel or vacation rental for every check-in date in a range, for stays of a chosen length. **Cross-linking**: The `property_token` parameter comes from the Google Hotels, Google Hotels Property, Google Hotels Autocomplete and Google Local APIs. Pass a `check_in_date` and `check_out_date` from the calendar to the Google Hotels Property API, with the same `property_token`, `adults`, `children_ages`, `currency` and `gl`, to see the offers for that stay. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Hotels Price Calendar security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Set to `google_hotels_price_calendar` for this API schema: type: string enum: ["google_hotels_price_calendar"] - name: property_token in: query required: true description: Unique property identifier token obtained from Google Hotels, Google Hotels Property, Google Hotels Autocomplete or Google Local results schema: type: string pattern: '^[A-Za-z0-9_-]{16,256}$' - name: check_in_date_start in: query required: false description: First check-in date of the calendar in YYYY-M-D format. Cannot be in the past. Defaults to today (UTC). schema: type: string pattern: '^\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12][0-9]|3[01])$' - name: check_in_date_end in: query required: false description: Last check-in date of the calendar in YYYY-M-D format, at most 364 days after check_in_date_start. Defaults to 30 days after check_in_date_start. schema: type: string pattern: '^\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12][0-9]|3[01])$' - name: nights in: query required: false description: Length of the stay priced for each check-in date. schema: type: integer minimum: 1 maximum: 30 default: 1 - name: adults in: query required: false description: Number of adult guests. Total of adults plus children cannot exceed 10. schema: type: integer minimum: 1 maximum: 10 default: 2 - name: children_ages in: query required: false description: Comma-separated ages of children (1-17 years). Maximum 5 children allowed. Total of adults plus children cannot exceed 10. schema: type: string maxLength: 64 - name: currency in: query required: false description: Currency code schema: type: string enum: ["ALL", "DZD", "ARS", "AMD", "AWG", "AUD", "AZN", "BSD", "BHD", "BYN", "BMD", "BAM", "BRL", "GBP", "BGN", "CAD", "XPF", "CLP", "CNY", "COP", "CRC", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "ILS", "JMD", "JPY", "JOD", "KZT", "KWD", "LBP", "MKD", "MYR", "MXN", "MDL", "MAD", "TWD", "NZD", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SEK", "CHF", "THB", "TRY", "UAH", "AED", "USD", "VND"] default: "USD" - name: gl in: query required: false description: Country code. Some countries show prices before taxes alongside the total, others show only the total including taxes. schema: type: string enum: ["AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AR", "AM", "AU", "AT", "AZ", "BS", "BH", "BD", "BY", "BE", "BZ", "BJ", "BT", "BO", "BA", "BW", "BR", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "CF", "TD", "CL", "CN", "CO", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "EE", "ET", "FJ", "FI", "FR", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GT", "GG", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LY", "LI", "LT", "LU", "MG", "MW", "MY", "MV", "ML", "MT", "MU", "MX", "FM", "MD", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NE", "NG", "NU", "MK", "NO", "OM", "PK", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "KR", "ES", "LK", "SH", "VC", "SR", "SE", "CH", "TW", "TJ", "TZ", "TH", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VE", "VN", "ZM", "ZW"] default: "US" - name: hl in: query required: false description: Interface language schema: type: string enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu", "en-gb", "en-us", "fil", "sr-latn"] default: "en" responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' calendar: type: array items: $ref: '#/components/schemas/CalendarDay' error: type: string description: Error message when no results are found SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Google Hotels URL for this property html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used property_token: type: string description: Property token used in search check_in_date_start: type: string description: First check-in date of the calendar check_in_date_end: type: string description: Last check-in date of the calendar nights: type: integer description: Length of each stay in nights adults: type: integer description: Number of adults children_ages: type: string description: Ages of children currency: type: string description: Currency code gl: type: string description: Country code hl: type: string description: Interface language CalendarDay: type: object required: [check_in_date, check_out_date] properties: check_in_date: type: string format: date description: Check-in date of the stay. check_out_date: type: string format: date description: Check-out date of the stay. price_per_night: description: Nightly price, with the price strings as Google Hotels labels them in the date picker, which can shorten the amount or leave out the currency symbol. allOf: - $ref: '#/components/schemas/Price' total_price: $ref: '#/components/schemas/Price' currency: type: string description: Currency code of the prices. is_lowest_price: type: boolean description: Whether the stay has the lowest total price in the calendar. Price: type: object properties: price: type: string description: Formatted price string extracted_price: type: number description: Numeric price value price_before_taxes: type: string description: Price before taxes string extracted_price_before_taxes: type: number description: Numeric price before taxes ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong