---
title: "Market Calendars"
method: GET
path: "/agent-hotels/market-calendars/"
tags: ["agent-hotels"]
---

# Market Calendars

`GET /agent-hotels/market-calendars/`

## Request

- Base URL: `https://api.helloaxel.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.helloaxel.com/agent-hotels/market-calendars/`
- Auth: none declared

The saved public calendars of several hotels: a city page's date grid.

A city page prices its top hotels against the upcoming weekends with one
catalog read, one unit of the shared limit, instead of one stays read per
hotel. The same bounded 98-night projection a hotel's own stays read
carries; saved Google calendar evidence only, never a quote. It never
starts supplier pricing and is cached like a hotel's stays. The ids are
sorted, so the same hotels in any order share one cache entry.

## Query parameters

- `hotel_ids` integer[], required
- `stays` string[], nullable

## Response `200`

Successful Response

- HotelMarketCalendars: The saved public calendars of several hotels in one read. A city page's date grid prices the city's top hotels against the upcoming stays. This is the same bounded 98-night projection a hotel's own stays read carries (``HotelStays.market_calendar``), for up to HOTEL_MARKET_CALENDARS_MAX_HOTELS catalog hotels at once, so the page is one read instead of one per hotel. Saved Google calendar evidence only: nothing here is a bookable quote, and the read never starts supplier pricing. Hotels that are not catalog hotels are left out; a catalog hotel without usable evidence is listed with no calendar.
  - `calendars` HotelMarketCalendarEntry[]
    - `hotel_id` integer, required
    - `calendar` HotelMarketCalendar: Bounded saved nightly evidence for 90 check-in days plus weekend extensions.
      - `start_date` string, date, required
      - `nightly_total_minor` integer[], required
      - `adults` 2
      - `rooms` 1
      - `currency` 'USD'
      - `source` 'google_hotels_calendar'
      - `observed_at` string, date-time, required
      - `source_snapshot` string, required
    - `prices` HotelMarketEstimate[]
      - `kind` 'estimated_market_total'
      - `stay` HotelStaySampleStay, required
        - `check_in` string, date, required
        - `check_out` string, date, required
        - `nights` integer, required
        - `adults` integer, required
        - `rooms` integer, required
      - `total` Money, required: Immutable money value stored as integer minor units. Amount is always stored in the smallest currency unit (cents, yen, pesos, etc). This avoids floating-point precision issues and matches payment processor standards. Examples: $19.99 USD -> Money(amount=1999, currency="USD") ¥1000 JPY -> Money(amount=1000, currency="JPY") $1000.00 CLP -> Money(amount=1000, currency="CLP") Serializes to {"amount": 1999, "currency": "USD"}. IMPORTANT: Use Money.from_decimal() for user-facing amounts like "$19.99". The constructor expects integer minor units (cents).
        - `amount` integer, required
        - `currency` string, required
      - `nightly_total_minor` integer[], required
      - `estimated_nights` string[]
      - `source` 'google_hotels_calendar'
      - `observed_at` string, date-time, required
      - `source_snapshot` string, required
    - `nightly_from` HotelMarketEstimate: Saved-calendar stay estimate; filled nights are identified separately.
      - `kind` 'estimated_market_total'
      - `stay` HotelStaySampleStay, required
        - `check_in` string, date, required
        - `check_out` string, date, required
        - `nights` integer, required
        - `adults` integer, required
        - `rooms` integer, required
      - `total` Money, required: Immutable money value stored as integer minor units. Amount is always stored in the smallest currency unit (cents, yen, pesos, etc). This avoids floating-point precision issues and matches payment processor standards. Examples: $19.99 USD -> Money(amount=1999, currency="USD") ¥1000 JPY -> Money(amount=1000, currency="JPY") $1000.00 CLP -> Money(amount=1000, currency="CLP") Serializes to {"amount": 1999, "currency": "USD"}. IMPORTANT: Use Money.from_decimal() for user-facing amounts like "$19.99". The constructor expects integer minor units (cents).
        - `amount` integer, required
        - `currency` string, required
      - `nightly_total_minor` integer[], required
      - `estimated_nights` string[]
      - `source` 'google_hotels_calendar'
      - `observed_at` string, date-time, required
      - `source_snapshot` string, required
  - `generated_at` string, date-time, required

## Other responses

- `422`: Validation Error

## Changes

> 103 revisions in range; 1 not diffed.

- **2026-11-02** `c22b50f81067`: 3 info
  - added the new optional `query` request parameter `stays`
  - added the optional property `calendars/items/nightly_from` to the response with the `200` status
  - added the optional property `calendars/items/prices` to the response with the `200` status
- **2026-10-30** `db4de8c1721b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/helloaxel/apis/client-api-gateway/changes/agent-hotels/market-calendars/get.md)

---

[API](https://skmtc.dev/helloaxel/apis/client-api-gateway.md) - [All operations](https://skmtc.dev/helloaxel/apis/client-api-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/helloaxel/apis/client-api-gateway/revisions/2d3c427963a4?raw)