Hotel availability for agents. A read-only, JSON-first CLI for searching hotel availability and rates across the major global brands — no API key, no account, no booking.
Amadeus decommissioned its Self-Service API on 2026-07-17, deactivating existing keys. It
was the only free, self-serve, globally-branded hotel API — every remaining official source
(Expedia Rapid, Booking.com Demand, Hotelbeds, RateHawk, Sabre) is partner-contract gated. That
left agents with no keyless way to check hotel availability. roost is that way.
v0.1.0 is not on PyPI yet. Until it publishes, install from source — the commands below are what will work the moment the release lands, and the badge row will gain a
pypibadge then. No install path is advertised here that doesn't currently work.
# From source (works today)
uv tool install git+https://github.com/rnwolfe/roost
# --- once v0.1.0 is published ---
# uv — recommended, zero install
uvx roost search "kyoto" --check-in 2026-10-02 --nights 3 --json
# uv tool — installed once, fastest for repeat agent calls
uv tool install roost
# pipx
pipx install roost
# pip
pip install roostRequires Python ≥3.10. Verify with roost doctor.
# What's available in Kyoto for three nights?
roost search "kyoto" --check-in 2026-10-02 --nights 3 --json
# Only the big chains, with free cancellation
roost search "chicago" --brand hyatt,marriott --free-cancellation --json
# Per-source rates for one property (richest with --backend serpapi)
roost rates "Sakura Cross Hotel Kyoto Kiyomizudera" --location kyoto --nights 3 --json
# When in the next 30 days is Lisbon cheapest? (plan the cost first)
roost dates "lisbon" --window 30 --nights 2 --dry-run
roost dates "lisbon" --window 30 --nights 2 --max-requests 8 --json
# Discover the brand ids
roost brands --search hyatt| roost | |
|---|---|
| Auth | None. No account, no API key, no card on file. |
| Dates | Real check-in/check-out, verified against what upstream echoes back. |
roost dates |
A bounded, throttled sweep answering which night is cheapest — --dry-run prices the request cost before spending it. |
| Failure modes | 20 BLOCKED (wait) and 21 SCHEMA_DRIFT (upgrade) are distinct, so an agent can branch. |
| Booking | Impossible. There is no code path, so nothing to gate. |
roost agent # the bundled usage + safety contract
roost schema # machine-readable command tree, exit codes, live safety stateroost is read-only — there is no booking command, and --allow-mutations is an inert
no-op kept for fleet contract uniformity. Every response carries a scope block declaring the
backend and whether the result was narrowed; rates are metasearch lead-in prices, not a
booking guarantee.
Exit codes distinguish the two failure modes that matter: 20 BLOCKED (you're being
throttled — stop and wait) from 21 SCHEMA_DRIFT (upstream changed — upgrade; retrying
won't help).
roost reads publicly visible, logged-out Google Hotels results at personal, single-user
scale, read-only. It never books, never transacts, never logs in, and never sends a credential.
The path it reads (/travel/hotels/…) is not disallowed by Google's robots.txt, and roost
enforces an in-code allowlist keeping it off every path that is.
Hard rule — reduce volume, never disguise it. No CAPTCHA solving, no proxy or IP rotation,
no residential proxies. If Google blocks roost, it stops — that's what the circuit breaker is
for. Not legal advice.
Access mechanics for the Google Hotels surface were mined from
jongan69/hotels (fast-hotels, MIT) — see NOTICE.
MIT — see LICENSE.