GUguesty
Calendar

Retrieve the optimized calendar for a single listing

Changed on

Use this endpoint to retrieve daily calendar availability and pricing for a given listing ID and date range with optimized response format.

View Parameter Behavior:

  • view=compact (default): Returns minimal data without blockIds array and detailed blocks object for better performance
  • view=full: Returns complete data including blockIds array for each calendar day and detailed blocks object with full block information

IMPORTANT: Multi-unit calendar availability is determined by unit allotment, not its status field. To calculate if a multi-unit has availability, use the following formula:

const isAvailable = _.isNumber(currentDay.allotment)?
currentDay.allotment > 0 : currentDay.status === 'available';
get/availability-pricing/api/calendar/listings/minified/{listingId}

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings/minified/{listingId}
  • Auth
    API key in header authorization

Path parameters

listingIdstring required

Listing ID

Query parameters

startDatestring date required

First day to be returned (format: YYYY-MM-DD)

endDatestring date required

Last day to be returned (format: YYYY-MM-DD)

includeAllotmentboolean

Return day objects including allotment

ignoreInactiveChildAllotmentboolean

Specify ignoreInactiveChildAllotment=true to exclude inactive sub-units from the allotment calculation. Default value is false.

ignoreUnlistedChildAllotmentboolean

Specify ignoreUnlistedChildAllotment=true to exclude unlisted sub-units from the allotment calculation. Default value is false.

view'compact' | 'full'

Calendar view type for optimized response

Response

Optimized calendar with available/unavailable dates. When view=compact, returns minimal data without blockIds and detailed blocks. When view=full, includes blockIds array and detailed blocks object. Returns only the data object containing the days information.

Example response

{
  "days": {
    "listingId": "687510715f4958000edfd6ba",
    "startDate": "2025-08-29",
    "endDate": "2025-09-10",
    "currency": "USD",
    "calendar": [
      {
        "date": "2025-08-29",
        "price": 11,
        "minNights": 1,
        "blocks": {
          "m": true
        },
        "isBasePrice": true,
        "isBaseMinNights": true,
        "requestToBook": false,
        "cta": false,
        "ctd": false
      },
      {
        "date": "2025-08-30",
        "price": 11,
        "minNights": 1,
        "blocks": {},
        "isBasePrice": true,
        "isBaseMinNights": true,
        "requestToBook": false,
        "cta": false,
        "ctd": false
      },
      {
        "date": "2025-09-02",
        "price": 11,
        "minNights": 1,
        "blocks": {
          "b": true
        },
        "isBasePrice": true,
        "isBaseMinNights": true,
        "requestToBook": false,
        "cta": false,
        "ctd": false
      }
    ],
    "blocks": {
      "68887c288e2fe15f60d7780b": {
        "_id": "68887c288e2fe15f60d7780b",
        "listingId": "687510715f4958000edfd6ba",
        "startDate": "2025-08-28T00:00:00.000Z",
        "endDate": "2025-08-29T00:00:00.000Z",
        "type": "m",
        "note": "test",
        "createdAt": "2025-07-29T07:45:44.572Z",
        "createdBy": "Test user"
      },
      "688b0ff5979306756a3d0f35": {
        "_id": "688b0ff5979306756a3d0f35",
        "listingId": "687510715f4958000edfd6ba",
        "startDate": "2025-09-02T00:00:00.000Z",
        "endDate": "2025-09-02T00:00:00.000Z",
        "type": "b",
        "reservationId": "688b0ff2d6befa642a6158ea",
        "reservation": {
          "_id": "688b0ff2d6befa642a6158ea",
          "listingId": "687510715f4958000edfd6ba",
          "status": "confirmed",
          "confirmationCode": "GY-fPLihWYL",
          "source": "manual",
          "checkInDateLocalized": "2025-09-02",
          "checkOutDateLocalized": "2025-09-03",
          "money": {
            "balanceDue": 30.7,
            "currency": "USD",
            "hostPayout": 30.7,
            "totalPaid": 0
          },
          "nightsCount": 1,
          "guestsCount": 1,
          "guest": {
            "_id": "688b0ff2098d648364433da5",
            "fullName": "Test full name"
          }
        },
        "createdAt": "2025-07-31T06:40:53.930Z",
        "createdBy": "Test user"
      }
    }
  }
}

Changes