---
title: "Query Listing Calendars"
method: POST
path: "/listings/calendar"
tags: ["Listing Calendar"]
---

# Query Listing Calendars

`POST /listings/calendar`

By sending a request to this endpoint, you can retrieve calendar information for multiple listings. This endpoint will return daily details on price, inventory, and restrictions for each listing.

## Request body

- object
  - `start_date` string, date, required — The start date for records. The date format is YYYY-MM-DD, and must be within 1 years from now.
  - `end_date` string, date, required — The end date for the calendar. The date format is YYYY-MM-DD, and must be within 3 years from now.
  - `listings` object[], required — A list of listing object. The listing object contains the listing id and channel type.
    - `channel_type` 'airbnb' | 'booking.com' | 'agoda' | 'expedia' | 'vrbo' | 'trip.com' | 'booking_site' | 'tujia_intl' | 'houfy', required — The type of the channel to be queried.
    - `listing_id` string, required — The unique identifier for different channels. <br>For example, the listing id for Airbnb is the Airbnb listing id, and the listing id for Booking.com is the Booking.com room id - rateplan id.

## Response `200`

- object
  - `request_id` string, required — Unique identifier for the request.
  - `error_code` integer, required — Numeric error code representing the status of the response. A value of `200` indicates success. <br> See the [Error Codes](/reference/error-manual#error-codes) section for more information.
  - `error_msg` string, required — Message detailing the status of the response.
  - `data` object, required
    - `listings` object[], required — A list of listing objects. Each listing object contains the listing id, channel type, and calendar.
      - `channel_type` 'airbnb' | 'booking.com' | 'agoda' | 'expedia' | 'vrbo' | 'trip.com' | 'booking_site' | 'tujia_intl' | 'hostex_direct' | 'tujia' | 'xiaozhu' | 'meituan_bnb' | 'meituan_hotel' | 'muniao' | 'fliggy' | 'zhukeyun' | 'tiktok' | 'xiaohongshu' | 'ctrip' | 'houfy', required — The type of the channel. See [Supported Channels](/reference/supported-channels) for more information.
      - `listing_id` string, required — The unique identifier for different channels. <br>For example, the listing id for Airbnb is the Airbnb listing id, and the listing id for Booking.com is the Booking.com room id - rateplan id.
      - `calendar` object[], required — A list of calendar objects. Each calendar object contains the date, price, and inventory for that date.
        - `date` string, date, required — The date of the calendar
        - `price` number, required — The price for the date
        - `inventory` integer, required — The inventory for the date
        - `restrictions` object — Restrictions for the date. Please notice that the range of fields for restrictions may vary across different channels. The fields listed below may not apply to all channels.
          - `closed_on_arrival` boolean — Reservations for the check-in date on this date are not allowed. Available for `airbnb` `booking.com` `agoda` `expedia` `booking_site` `trip.com`.
          - `closed_on_departure` boolean — Reservations for the check-out date on this date are not allowed. Available for `airbnb` `booking.com` `agoda` `expedia` `booking_site` `trip.com`.
          - `min_stay_on_arrival` integer — Reservations including this date must not be shorter than the specified number of days. Available for `airbnb` `booking.com` `agoda` `expedia` `booking_site` `trip.com`.
          - `max_stay_on_arrival` integer — Reservations including this date must not be longer than the specified number of days. Available for `airbnb` `booking.com` `agoda` `expedia` `booking_site` `trip.com`.
          - `min_stay_through` integer — Reservations including this date must not be shorter than the specified number of days. Available for `booking.com` `agoda` `trip.com`.
          - `max_stay_through` integer — Reservations including this date must not be longer than the specified number of days. Available for `booking.com` `trip.com`.
          - `min_advance_reservation` string — The minimum number of days and/or hours that guests must book in advance (before the planned check-in or check-out date). The search date is counted as one of the days in the restriction length. This field requires the format like 'xDxH'. Examples: 4D = four days; 4D4H = four days and four hours. Available for `booking.com` `trip.com`.
          - `max_advance_reservation` string — The maximum number of days and/or hours that guests may book in advance (before the planned check-in or check-out date). The search date is counted as one of the days in the restriction length. This field requires the format like 'xDxH'. Examples: 4D = four days; 4D4H = four days and four hours. Available for `booking.com` `trip.com`.
          - `exact_stay_on_arrival` integer — Reservations with the check-in date on this date must be equal to the specified number of days. Available for `booking.com`.

---

[API](https://skmtc.net/hostex/apis/hostex-api.md) · [All operations](https://skmtc.net/hostex/apis/hostex-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hostex/hostex-api/revisions/a3fa555dee66/schema)