Best Time To Book Hotels Booking Timing API

openapi: 3.2.0
info:
  title: Best Time To Book Hotels Public Booking Timing API
  version: 1.0.0
  summary: Read-only JSON access to hotel booking-timing research, last-minute deal history, and agent-readable Markdown.
  description: 'Free, unauthenticated, read-only endpoints backed by the same price-observation

    dataset that powers the site. Every response describes observed historical prices,

    not a forecast for a specific stay.


    There is no API key. Requests are rate limited per client IP (60 requests per

    minute per endpoint); exceeding the limit returns 429 with `Retry-After`.


    Conversational access to the same data is available through the MCP server at

    /api/mcp, described separately by /server.json.'
  contact:
    name: Best Time To Book Hotels
    url: https://www.besttimetobookhotels.com/docs/api
servers:
- url: https://www.besttimetobookhotels.com
security: []
tags:
- name: booking-timing
  description: When to book, from observed prices.
paths:
  /api/booking-advice:
    get:
      tags:
      - booking-timing
      operationId: getBookingAdvice
      summary: Booking advice for a city and a specific stay
      description: 'Combines the city''s current price trend with observed booking-date history for the requested stay. Returns `advice: null` when the stay has too little observed history to say anything.'
      parameters:
      - name: citySlug
        in: query
        required: true
        description: City slug as used on /cities/{citySlug}, e.g. `paris`.
        schema:
          type: string
        example: paris
      - name: countrySlug
        in: query
        required: true
        description: Country slug for the city, e.g. `france`.
        schema:
          type: string
        example: france
      - name: checkIn
        in: query
        required: true
        description: Check-in date.
        schema:
          $ref: '#/components/schemas/IsoDate'
      - name: checkOut
        in: query
        required: false
        description: Check-out date. Dropped when it is not strictly after `checkIn`.
        schema:
          $ref: '#/components/schemas/IsoDate'
      - name: locale
        in: query
        required: false
        description: Locale for generated advice copy. Defaults to `en`.
        schema:
          type: string
          default: en
      responses:
        '200':
          description: Advice for the stay, or `null` when history is too thin.
          headers:
            Cache-Control:
              $ref: '#/components/headers/CachedResponse'
          content:
            application/json:
              schema:
                type: object
                required:
                - advice
                properties:
                  advice:
                    oneOf:
                    - $ref: '#/components/schemas/BookingAdvice'
                    - type: 'null'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/hotel-booking-lead-time:
    get:
      tags:
      - booking-timing
      operationId: exploreBookingLeadTime
      summary: Search or read the booking lead-time study
      description: Backs the explorer in the booking lead-time guide. Pass exactly one of `q` (typeahead search over cities and hotels) or `id` (a record returned by that search). A `q` shorter than two characters returns an empty suggestion list rather than an error.
      parameters:
      - name: q
        in: query
        required: false
        description: Search text. Mutually exclusive with `id`.
        schema:
          type: string
        example: lisbon
      - name: id
        in: query
        required: false
        description: Record id from a previous search. Mutually exclusive with `q`.
        schema:
          type: string
      responses:
        '200':
          description: Suggestions for `q`, or the single record for `id`.
          headers:
            Cache-Control:
              $ref: '#/components/headers/CachedResponse'
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  required:
                  - suggestions
                  properties:
                    suggestions:
                      type: array
                      items:
                        $ref: '#/components/schemas/LeadTimeSuggestion'
                - type: object
                  required:
                  - record
                  properties:
                    record:
                      $ref: '#/components/schemas/LeadTimeRecord'
        '400':
          description: Neither or both of `q` and `id` were supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    RateLimited:
      description: Per-IP rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix time in seconds when the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No data matches the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: The endpoint's data source is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Required parameters are missing or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    LeadTimeSuggestion:
      type: object
      required:
      - context
      - id
      - kind
      - label
      properties:
        context:
          type: string
          description: Disambiguating text, e.g. the country.
        id:
          type: string
          description: Pass back as `id` to read the record.
        kind:
          type: string
          enum:
          - city
          - hotel
        label:
          type: string
    IsoDate:
      type: string
      format: date
      pattern: ^\d{4}-\d{2}-\d{2}$
      examples:
      - '2026-09-14'
    LeadTimeRecord:
      type: object
      description: A city or hotel from the booking lead-time study, with its booking-window results.
      required:
      - citySlug
      - countrySlug
      - id
      - kind
      - label
      - windows
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - city
          - hotel
        label:
          type: string
        context:
          type: string
        citySlug:
          type: string
        countrySlug:
          type: string
        hotelSlug:
          type: string
          description: Present on hotel records only.
        hotelCount:
          type: integer
          description: Qualifying hotels behind a city record.
        windows:
          type: array
          description: Per booking-window results, keyed by lead-time bucket such as `90+` or `2-7`.
          items:
            type: object
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    BookingAdvice:
      type: object
      description: Advice for one stay. Prices are medians of observed nightly rates in USD.
      required:
      - basis
      - checkIn
      - citySlug
      - confidence
      - countrySlug
      - daysUntilCheckIn
      - recommendation
      - relativeToYear
      - season
      - targetMedianPrice
      - yearlyMedianPrice
      properties:
        basis:
          type: string
          description: Which evidence the recommendation rests on.
        checkIn:
          $ref: '#/components/schemas/IsoDate'
        checkOut:
          $ref: '#/components/schemas/IsoDate'
        citySlug:
          type: string
        countrySlug:
          type: string
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        daysUntilCheckIn:
          type: integer
        recommendation:
          type: string
          description: The advice verdict, e.g. `book_now` or `wait_until_window`.
        relativeToYear:
          type: string
          description: How the stay's median compares with the yearly median.
        season:
          type: string
        targetMedianPrice:
          type: number
          description: Observed median nightly price for the requested stay, USD.
        yearlyMedianPrice:
          type: number
          description: Observed median nightly price across the year, USD.
        history:
          type: object
          description: Summary of observed booking-date prices for this stay.
        historyTrend:
          type: object
          description: Direction and size of the recent price move.
  headers:
    CachedResponse:
      description: Shared-cache directives for this response.
      schema:
        type: string
externalDocs:
  description: Public API documentation
  url: https://www.besttimetobookhotels.com/docs/api