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 roost
Requires 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 state
roost 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.