Best Time To Book Hotels Deals API

openapi: 3.2.0
info:
  title: Best Time To Book Hotels Public Deals 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: Deals
  description: Last-minute deal price history.
paths:
  /api/last-minute-deal-history:
    get:
      tags:
      - Deals
      operationId: getLastMinuteDealHistory
      summary: Observed price history behind a last-minute deal
      description: Returns the observed median price series for one hotel and check-in date, plus the baseline the current deal is discounted against.
      parameters:
      - name: citySlug
        in: query
        required: true
        schema:
          type: string
        example: dubai
      - name: hotelSlug
        in: query
        required: true
        schema:
          type: string
      - name: checkIn
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/IsoDate'
      responses:
        '200':
          description: The deal's price history.
          headers:
            Cache-Control:
              $ref: '#/components/headers/CachedResponse'
          content:
            application/json:
              schema:
                type: object
                required:
                - series
                properties:
                  series:
                    $ref: '#/components/schemas/DealHistorySeries'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: No deal history is stored for this stay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
    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:
    IsoDate:
      type: string
      format: date
      pattern: ^\d{4}-\d{2}-\d{2}$
      examples:
      - '2026-09-14'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    DealHistorySeries:
      type: object
      required:
      - baselineUsd
      - checkIn
      - checkOut
      - points
      - snapshotDate
      - snapshotDropPercent
      - snapshotUsd
      properties:
        baselineUsd:
          type: number
          description: Typical observed nightly price for this stay, USD.
        checkIn:
          $ref: '#/components/schemas/IsoDate'
        checkOut:
          $ref: '#/components/schemas/IsoDate'
        snapshotDate:
          $ref: '#/components/schemas/IsoDate'
          description: Observation date the published deal was taken from.
        snapshotUsd:
          type: number
        snapshotDropPercent:
          type: number
          description: Percent below `baselineUsd` at `snapshotDate`.
        points:
          type: array
          items:
            $ref: '#/components/schemas/DealHistoryPoint'
    DealHistoryPoint:
      type: object
      required:
      - daysBeforeCheckIn
      - medianUsd
      - scrapedDate
      - window
      properties:
        daysBeforeCheckIn:
          type: integer
        medianUsd:
          type: number
        scrapedDate:
          $ref: '#/components/schemas/IsoDate'
        window:
          type: string
          enum:
          - baseline
          - near
          - outside
          description: Which lead-time window the observation falls in.
  headers:
    CachedResponse:
      description: Shared-cache directives for this response.
      schema:
        type: string
externalDocs:
  description: Public API documentation
  url: https://www.besttimetobookhotels.com/docs/api