Award Travel Finder Hotels API
The Hotels API from Award Travel Finder — 5 operation(s) for hotels.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/awardtravelfinder-com:awardtravelfinder-com-hotels-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Award Travel Finder API V1 Hotels API
version: v1
description: 'API for searching award flight availability and pricing across multiple airlines, plus hotel search (city list and property detail with cash rates and major-chain award pricing). Availability searches that are still running return 202 Accepted with status pending, retry_after, and a Retry-After header (previously 503). A request scoped only to an open-breaker source stays 503, names that source, and includes Retry-After. A multi-airline search returns 200 with partial true and a per-source status list when other sources answered. Optional cached_only=1 is opt-in for every tier: a hit is 200, a miss is 202 pending and enqueues one background search. Per-key rate and concurrency limits return 429 with Retry-After. 202, 429, and 503 do not consume the monthly quota. Each hotel list or detail request counts as one call against the monthly quota.'
contact:
name: Award Travel Finder
url: https://awardtravelfinder.com
servers:
- url: https://awardtravelfinder.com
description: Production server
- url: http://localhost:3000
description: Development server
security:
- ApiKeyAuth: []
tags:
- name: Hotels
paths:
/api/v1/hotels:
get:
summary: Search hotels in a city
tags:
- Hotels
description: List hotels in a city for check-in and check-out dates. Returns live cash rates where available, major-chain award nights, and points prices in popular card currencies. Requires Premium or a commercial API plan (Evaluation, Developer, Partner, or Scale). Counts as one call against the monthly quota.
parameters:
- name: X-API-Key
in: header
required: true
schema:
type: string
description: API key for authentication
- name: city
in: query
required: true
schema:
type: string
description: City, neighbourhood, or landmark
- name: check_in_date
in: query
required: true
schema:
type: string
format: date
- name: check_out_date
in: query
required: true
schema:
type: string
format: date
- name: adults
in: query
required: false
schema:
type: integer
default: 2
- name: rooms
in: query
required: false
schema:
type: integer
default: 1
- name: limit
in: query
required: false
schema:
type: integer
default: 20
maximum: 40
responses:
'200':
description: Hotels found
'403':
description: Plan does not include hotel city search or detail
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Hotel search requires Premium or a commercial API plan (Evaluation, Developer, Partner, or Scale).
'401':
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API key required
'422':
description: Invalid or unprocessable parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
'429':
description: Monthly API quota exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API usage limit exceeded
tier:
type: string
plan:
type: string
monthly_limit:
type: integer
remaining_calls:
type: integer
example: 0
upgrade_message:
type: string
upgrade_url:
type: string
operationId: getApiV1Hotels
x-operation-id-source: derived
/api/v1/hotels/{id}:
get:
summary: Hotel detail with room rates and points prices
tags:
- Hotels
description: Live cash rates by booking site and the full points-price table for one hotel id from the list endpoint. Requires Premium or a commercial API plan. Counts as one call against the monthly quota.
parameters:
- name: X-API-Key
in: header
required: true
schema:
type: string
description: API key for authentication
- name: id
in: path
required: true
schema:
type: string
description: Hotel id from GET /api/v1/hotels (starts with htl_)
- name: check_in_date
in: query
required: true
schema:
type: string
format: date
- name: check_out_date
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Hotel detail
'403':
description: Plan does not include hotel city search or detail
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Hotel search requires Premium or a commercial API plan (Evaluation, Developer, Partner, or Scale).
'401':
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API key required
'422':
description: Invalid or unprocessable parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
'429':
description: Monthly API quota exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API usage limit exceeded
tier:
type: string
plan:
type: string
monthly_limit:
type: integer
remaining_calls:
type: integer
example: 0
upgrade_message:
type: string
upgrade_url:
type: string
operationId: getApiV1HotelsById
x-operation-id-source: derived
/api/v1/hotels/search:
get:
summary: Search hotels
tags:
- Hotels
description: Search hotels by name, city, or brand. Returns hotel ids to use with the availability endpoint. Counts as one API call against the monthly quota when authenticated on a paid or evaluation plan.
parameters:
- name: X-API-Key
in: header
required: true
description: API key for authentication
schema:
type: string
- name: query
in: query
required: true
description: Hotel name or city
schema:
type: string
- name: brand
in: query
required: false
description: Brand filter, e.g. hyatt
schema:
type: string
- name: limit
in: query
required: false
description: Max results (default 20, max 50)
schema:
type: integer
default: 20
maximum: 50
responses:
'200':
description: Matching hotels
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
query:
type: string
brand:
type: string
hotels_found:
type: integer
example: 1
hotels:
type: array
items:
type: object
properties:
id:
type: string
example: abc123
name:
type: string
example: Grand Hyatt Tokyo
brand:
type: string
example: Hyatt
sub_brand:
type: string
city:
type: string
example: Tokyo
country:
type: string
example: Japan
link:
type: string
format: uri
message:
type: string
description: Present when no hotels matched the query
usage:
type: object
properties:
tier:
type: string
plan:
type: string
cabin_access:
type: string
remaining_calls:
type: integer
monthly_limit:
type: integer
period:
type: string
reset_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
upgrade_url:
type: string
'401':
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API key required
'422':
description: Invalid or unprocessable parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
'429':
description: Monthly API quota exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API usage limit exceeded
tier:
type: string
plan:
type: string
monthly_limit:
type: integer
remaining_calls:
type: integer
example: 0
upgrade_message:
type: string
upgrade_url:
type: string
'403':
description: Forbidden — account not authorized for this operation
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
operationId: getApiV1HotelsSearch
x-operation-id-source: derived
/api/v1/hotels/availability:
get:
summary: Get hotel award availability
tags:
- Hotels
description: Award points rates and cash rates per room for a hotel on a check-in date. Counts as one API call against the monthly quota when authenticated on a paid or evaluation plan.
parameters:
- name: X-API-Key
in: header
required: true
description: API key for authentication
schema:
type: string
- name: hotel_id
in: query
required: true
description: Hotel id from GET /api/v1/hotels/search
schema:
type: string
- name: check_in_date
in: query
required: true
description: Check-in date (YYYY-MM-DD)
schema:
type: string
format: date
- name: nights
in: query
required: false
description: Number of nights (default 1)
schema:
type: integer
default: 1
responses:
'200':
description: Room-level award and cash rates
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
hotel_id:
type: string
example: abc123
check_in_date:
type: string
example: '2027-03-15'
nights:
type: integer
example: 2
rooms_found:
type: integer
example: 1
rooms:
type: array
items:
type: object
properties:
room_type:
type: string
example: King Room
rate_plan:
type: string
example: Standard
points:
type: integer
example: 25000
points_display:
type: string
example: 25,000
cash_rate_usd:
type: number
example: 320.0
rooms_available:
type: integer
example: 3
message:
type: string
description: Present when no award rooms were found
usage:
type: object
properties:
tier:
type: string
plan:
type: string
cabin_access:
type: string
remaining_calls:
type: integer
monthly_limit:
type: integer
period:
type: string
reset_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
upgrade_url:
type: string
'401':
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API key required
'422':
description: Invalid or unprocessable parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
'429':
description: Monthly API quota exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API usage limit exceeded
tier:
type: string
plan:
type: string
monthly_limit:
type: integer
remaining_calls:
type: integer
example: 0
upgrade_message:
type: string
upgrade_url:
type: string
'403':
description: Forbidden — account not authorized for this operation
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
operationId: getApiV1HotelsAvailability
x-operation-id-source: derived
/api/v1/hotels/brands:
get:
summary: List hotel brands
tags:
- Hotels
description: Supported hotel loyalty brands and sub-brands.
parameters:
- name: X-API-Key
in: header
required: true
description: API key for authentication
schema:
type: string
responses:
'200':
description: Brand hierarchy
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
brands_count:
type: integer
example: 8
brands:
type: array
items:
type: object
properties:
name:
type: string
example: Hyatt
program:
type: string
example: World of Hyatt
sub_brands:
type: array
items:
type: string
example:
- Grand Hyatt
message:
type: string
description: Present when brands could not be loaded
usage:
type: object
properties:
tier:
type: string
plan:
type: string
cabin_access:
type: string
remaining_calls:
type: integer
monthly_limit:
type: integer
period:
type: string
reset_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
upgrade_url:
type: string
'401':
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API key required
'422':
description: Invalid or unprocessable parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
'429':
description: Monthly API quota exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API usage limit exceeded
tier:
type: string
plan:
type: string
monthly_limit:
type: integer
remaining_calls:
type: integer
example: 0
upgrade_message:
type: string
upgrade_url:
type: string
'403':
description: Forbidden — account not authorized for this operation
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
operationId: getApiV1HotelsBrands
x-operation-id-source: derived
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
name: X-API-Key
in: header
description: 'API key for the REST API and CLI, sent as the X-API-Key header. Autonomous agents can self-register for a free-tier key in one unauthenticated call: POST /api/v1/agent/register. The MCP server at https://mcp.awardtravelfinder.com/mcp does NOT accept this key - it is OAuth 2.1 only (scope mcp:read), with Dynamic Client Registration at POST /oauth/register.'
x-service-info:
name: Award Travel Finder
description: 'Award seat availability, award chart pricing and points valuations. Current airline coverage: https://awardtravelfinder.com/coverage.json.'
categories:
- travel
- flight-search
- loyalty-programs
documentation: https://awardtravelfinder.com/developers
pricing_url: https://awardtravelfinder.com/pricing