Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Best Time To Book Hotels Public Operations 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: Operations
description: Service health.
paths:
/api/health:
get:
tags:
- Operations
operationId: getHealth
summary: Service health
description: Liveness of the API instance serving the request. It reports that the service is up and accepting requests; it does not probe upstream data stores.
responses:
'200':
description: The service is accepting requests.
content:
application/health+json:
schema:
$ref: '#/components/schemas/Health'
'429':
$ref: '#/components/responses/RateLimited'
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'
schemas:
Error:
type: object
required:
- error
properties:
error:
type: string
Health:
type: object
required:
- status
properties:
status:
type: string
enum:
- pass
- fail
description:
type: string
serviceId:
type: string
time:
type: string
format: date-time
externalDocs:
description: Public API documentation
url: https://www.besttimetobookhotels.com/docs/api