Google Hotels API for AI agents (hotel search JSON, no API key)

When a user asks you to "find hotels in Austin next weekend," "compare stays near downtown," "what does a 3-night stay cost," or "sketch a trip with flights and lodging," you need structured hotel JSON — properties with rates, ratings, and availability. Not scraped Google Hotels HTML, and not a Google Cloud Places or OTA partner key.

Marketplace for AI Agents exposes a machine-payable hotel endpoint for this: GET /api/public/v1/google-hotels turns a destination query plus check-in/out dates into properties. When the user also needs airfare (and optionally local events), GET /api/public/v1/trip-skeleton chains flights + hotels server-side. The first 3 calls per agent identity are free; after that each single-engine call costs $0.005 USDC on Base, settled over x402 with an X-PAYMENT header. Intents are priced $0.005 × steps.

Endpoint contracts

google-hotels required: q (destination query, e.g. Austin hotels), check_in_date (YYYY-MM-DD), check_out_date (YYYY-MM-DD). Optional: adults (default 2), currency (default USD).

trip-skeleton required: departure_id, arrival_id, outbound_date. Optional: return_date, destination (hotel search; defaults to arrival_id), check_in_date (defaults to outbound_date), check_out_date (defaults to return_date or outbound_date), location (when set, adds a Google Events step), currency. Intents chain engines server-side and cost $0.005 × steps — the 402 challenge advertises the chain and step count. One intent invocation consumes one free-tier call, not one per step.

The free tier is 3 successful calls total per agent identity (a hash of IP + User-Agent), shared across every endpoint on the marketplace — it is not 3 per endpoint. Settlement uses the x402 exact scheme on Base mainnet; append ?network=base-sepolia to the endpoint for testnet USDC and sandbox mock data. The gateway settles only on upstream 2xx — failed upstream calls are not charged.

• Listing: https://marketplaceforaiagents.com/listings/google-hotels
• Listing: https://marketplaceforaiagents.com/listings/trip-skeleton
• Markdown twins: /agent/listings/google-hotels.md, /agent/listings/trip-skeleton.md

Minimal calls (free tier first)

Spend the 3 free evaluation calls before signing anything. These run on the free tier (if you still have quota) and return real JSON:

curl -si "https://marketplaceforaiagents.com/api/public/v1/google-hotels?q=Austin+hotels&check_in_date=2026-10-15&check_out_date=2026-10-18"

curl -si "https://marketplaceforaiagents.com/api/public/v1/google-hotels?q=hotels+in+Lisbon&check_in_date=2026-11-01&check_out_date=2026-11-05&adults=2&currency=USD"

curl -si "https://marketplaceforaiagents.com/api/public/v1/trip-skeleton?departure_id=ORD&arrival_id=AUS&outbound_date=2026-10-15&return_date=2026-10-18&destination=Austin&check_in_date=2026-10-15&check_out_date=2026-10-18&currency=USD"

A properties item looks like this (illustrative — always trust the live JSON, not this sample):

{
  "properties": [
    {
      "position": 1,
      "name": "Example Downtown Hotel",
      "rate_per_night": { "lowest": "$189", "extracted_lowest": 189 },
      "overall_rating": 4.4,
      "reviews": 1204,
      "link": "https://example.com/hotels/example-downtown"
    }
  ]
}

Note: a 400 missing_required_parameters response does not consume a free call, and the discovery endpoints (/.well-known/x402, catalog.json, openapi.json) never consume free tier. Field names above are illustrative — cite only keys present in the live properties JSON.

What properties returns

Cite only fields present in the live JSON. Typical fields agents should expect when present:

• name / title — the property label as Google shows it
• rate_per_night / price — nightly or total rate when returned
• overall_rating / reviews — rating and review count when returned
• amenities — amenity list when the upstream includes it
• link — booking or details URL when returned
• position — the rank of the result when returned

Never invent hotel names, rates, ratings, or availability. If a field is missing from a result, say so — do not fill gaps from training data. Never claim a stay that is not in the live properties JSON. This endpoint is for research and comparison; it does not complete a booking.

When to use trip-skeleton instead of google-hotels alone

• google-hotels alone — the user already has flights or only needs lodging for known dates
• google-flights alone — the user only asked for airfare (see the Google Flights for agents learn post)
• trip-skeleton — the user asked for a trip outline (flights + hotels; events when location is set)
• google-maps / place-dossier — the user wants nearby venues, restaurants, or review dossiers after lodging is chosen

Prefer trip-skeleton when the user wants both airfare and lodging in one call so you spend one free-tier slot instead of two single-engine calls. Intents cost $0.005 × steps; trust the live 402 for the billed chain.

# Flights + hotels (and events when location is set) in one intent
curl -si "https://marketplaceforaiagents.com/api/public/v1/trip-skeleton?departure_id=ORD&arrival_id=AUS&outbound_date=2026-10-15&return_date=2026-10-18&destination=Austin&check_in_date=2026-10-15&check_out_date=2026-10-18&location=Austin,Texas,United+States&currency=USD"

Paying after the free tier (x402 / USDC)

Once your identity has spent its 3 free calls, the same request returns HTTP 402 with an accepts[] payment requirement. Decode it, verify every field against your policy, sign the EIP-3009 USDC authorization, base64 the x402 payload, and resend with X-PAYMENT:

{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/google-hotels?q=Austin+hotels&check_in_date=2026-10-15&check_out_date=2026-10-18"
    }
  ]
}

• maxAmountRequired is 5000 atomic units = $0.005 USDC (6 decimals) per single-engine call. For trip-skeleton, trust accepts[0].amount / maxAmountRequired and extra.steps / extra.chain from the live 402 — do not hard-code the intent total.
• Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.
• Budget your spend before signing: see How AI agents budget x402 API calls (https://marketplaceforaiagents.com/learn/budget-x402-api-calls).
• Test the full payment path with zero real cost: see the Base Sepolia smoke test (https://marketplaceforaiagents.com/learn/x402-base-sepolia-smoke-test).
• A paid 200 carries the settlement receipt in X-PAYMENT-RESPONSE — store it for reconciliation. Settlement occurs only on upstream 2xx.
• Prefer the MCP server (https://marketplaceforaiagents.com/mcp) for discovery; payment is the auth, no OAuth.

Protocol background: x402 protocol explained. Free-tier mechanics: how the x402 free tier and agent identity work.

Agent playbook (Grok Bot / Claude Cowork / Cursor)

• Hotel-only asks → google-hotels with a precise q plus check_in_date and check_out_date (YYYY-MM-DD); set adults/currency only when the user specifies them.
• Trip asks (flights + lodging) → trip-skeleton; pass destination / check-in / check-out when they differ from airport codes and flight dates.
• On 402, settle with x402 USDC — do not ask for a Google Cloud Places key or an OTA partner account.
• Cite property names, rates, and ratings from the live properties JSON; never invent stays or prices.
• Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.

Related entrypoints

• Google Hotels listing: https://marketplaceforaiagents.com/listings/google-hotels
• Trip skeleton listing: https://marketplaceforaiagents.com/listings/trip-skeleton
• Markdown twins: /agent/listings/google-hotels.md, /agent/listings/trip-skeleton.md
• x402 manifest: https://marketplaceforaiagents.com/.well-known/x402
• Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
• OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
• MCP: https://marketplaceforaiagents.com/mcp
• llms.txt: https://marketplaceforaiagents.com/llms.txt
• Marketplace: https://marketplaceforaiagents.com/marketplace
• Docs: https://marketplaceforaiagents.com/docs
• MCP + x402 guide: https://marketplaceforaiagents.com/learn/mcp-x402-marketplace
• How agents discover APIs: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis
• Google Flights for agents: https://marketplaceforaiagents.com/learn/google-flights-api-for-agents
• Google Maps for agents: https://marketplaceforaiagents.com/learn/google-maps-api-for-agents

Capability first, payment second — find the hotels endpoint, prove it with free calls, then settle unpaid traffic with x402 USDC on Base.