Skip to main content

Availability Details

Documentation for GET /api/v1/public/availability endpoint.

GET https://staging.villra.com/api/v1/public/availability?filter[property_id]=78c7e569-12cb-44dc-ac67-5503b146e106&filter[date][gte]=2025-05-31&filter[date][lte]=2025-06-01

Notes on the Randomized Fields

  1. rooms array length: Expanded to three rooms (instead of one).

  2. roomId values: Each replaced with new UUIDs (c3f94a27-…, b2e5c6d1-…, e4f2b3a9-…).

  3. Room Titles:

    • "Garden View Deluxe"
    • "Poolside Family Suite"
    • "Penthouse Suite – Skyline View"

  4. Occupancy Values (occ_adults, occ_children, occ_infants): Changed to realistic numbers per room type.

  5. Photo arrays:

    • First room has a single photo object with new id, url, and non-null description.
    • Second room’s Photo is an empty array.
    • Third room includes two photo objects with new IDs, one with description = null, one with a valid caption.

  6. Facilities arrays:

    • First room: ["wifi", "air_conditioning", "minibar"]
    • Second room: [] (no facilities listed)
    • Third room: ["jacuzzi", "private_terrace"]

  7. isAvailable flags:

    • Room 1: true
    • Room 2: false
    • Room 3: true

  8. ratePlansAvailability entries:

    • Each room has between one and two rate plans with randomized ratePlanId, title, and totalRate.
    • Non-available rate plans show "isAvailable": false with "totalRate": 0.
    • Available plans show "isAvailable": true with a non-zero totalRate (e.g., 1250.75, 3420.00, 2980.50).

  9. meta.filters: Echoes back the filter values exactly as passed in the request.

Field Descriptions​

Top-Level Object​

  • rooms

    • Type: Array of objects
    • Description: List of rooms within the specified property, each containing availability and rate details for the requested date span.

  • meta

    • Type: Object
    • Description: Echo of the filters used in the request. Useful for client-side verification that you received the correct filters.

meta.filters​

  • property_id

    • Type: String (UUID)
    • Example: "78c7e569-12cb-44dc-ac67-5503b146e106"
    • Description: The same property ID passed as a query parameter.

  • date.gte

    • Type: String (YYYY-MM-DD)
    • Example: "2025-05-31"
    • Description: Start date (inclusive) for the availability check.

  • date.lte

    • Type: String (YYYY-MM-DD)
    • Example: "2025-06-01"
    • Description: End date (inclusive) for the availability check.

Inside Each Room Object​

roomId​

  • Type: string (UUID)
  • Example: "c3f94a27-8db1-4f29-9e2c-c7f1a5d76b33"
  • Description: Unique identifier of the room. Matches the canonical room record in your database.

room​

  • Type: object

  • Description: Contains metadata about the room itself.

    • title

      • Type: string
      • Example: "Penthouse Suite – Skyline View"
      • Description: Human-friendly room name.

    • occ_adults

      • Type: integer
      • Example: 2
      • Description: Maximum number of adults allowed in this room.

    • occ_children

      • Type: integer
      • Example: 1
      • Description: Maximum number of children allowed.

    • occ_infants

      • Type: integer
      • Example: 0
      • Description: Maximum number of infants allowed.

    • Photo

      • Type: Array of photo objects

      • Description: Zero or more photos associated with this room. Each photo object includes:

        • id (UUID)
        • url (string)
        • description (string or null)
        • position (integer)

    • facilities

      • Type: Array of strings
      • Example: ["jacuzzi", "private_terrace"]
      • Description: List of facility codes (e.g., "wifi", "air_conditioning") or names. If empty, no facilities are specified.

isAvailable​

  • Type: boolean

  • Example: true or false

  • Description: Indicates whether any rate plan for this room is available across the entire date range.

    • true means at least one rate plan is fully available from gte to lte.
    • false means none of the listed rate plans are available throughout the entire date range.

ratePlansAvailability​

  • Type: Array of objects

  • Description: Details for each rate plan linked to this room. Even if the room-level isAvailable is false, you may see one or more plans listed—each with its own availability flag.

    • ratePlanId

      • Type: string (UUID)
      • Example: "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f"
      • Description: Unique identifier for a specific rate plan.

    • title

      • Type: string
      • Example: "Advance Purchase – Penthouse"
      • Description: Human-readable name of the rate plan, which often indicates conditions (e.g., refundable, non-refundable).

    • isAvailable

      • Type: boolean
      • Example: true or false
      • Description: Whether this particular rate plan can be booked for the entire date window.

    • totalRate

      • Type: number (decimal)
      • Example: 2980.50
      • Description: Total cost in the property’s primary currency for booking this rate plan across all nights between gte and lte. If isAvailable is false, it is customary to set totalRate to 0.

How to Consume This Endpoint​

  1. Construct Your Query: Identify the property UUID and desired date range. For example, if you want availability for Property 78c7e569-12cb-44dc-ac67-5503b146e106 from May 31, 2025 through June 1, 2025, you append:

    ?filter[property_id]=78c7e569-12cb-44dc-ac67-5503b146e106
    &filter[date][gte]=2025-05-31
    &filter[date][lte]=2025-06-01

  2. Send the GET Request: Use curl, Postman, or any HTTP library, ensuring you URL-encode the query parameters if constructing programmatically.

  3. Parse the JSON Payload:

    • Iterate over the rooms array.

    • For each room, inspect isAvailable.

      • If true, loop through ratePlansAvailability to display available rate plans and their totalRate.
      • If false, you can surface a “Sold Out” or “No Availability” message for that room.

  4. Apply Business Logic:

    • Display room names and photos to end users.
    • Highlight which rate plans are available (and at what price).
    • If you implement dynamic pricing, adjust front-end labels based on totalRate.

Quick Reference Table​

FieldTypeDescription
roomsarray[object]List of room availability details.
rooms[].roomIdstring (UUID)Unique identifier for a room.
rooms[].room.titlestringHuman-readable room name.
rooms[].room.occ_adultsintegerMax number of adults allowed.
rooms[].room.occ_childrenintegerMax number of children allowed.
rooms[].room.occ_infantsintegerMax number of infants allowed.
rooms[].room.Photoarray[object]List of photo objects (ID, URL, description, position).
rooms[].room.facilitiesarray[string]List of facility codes/names (may be empty).
rooms[].isAvailablebooleanTrue if at least one rate plan is available for entire date range.
rooms[].ratePlansAvailabilityarray[object]Detailed availability per rate plan.
rooms[].ratePlansAvailability[].ratePlanIdstring (UUID)Unique ID of the rate plan.
rooms[].ratePlansAvailability[].titlestringDescriptive rate plan name.
rooms[].ratePlansAvailability[].isAvailablebooleanTrue if this rate plan is fully bookable.
rooms[].ratePlansAvailability[].totalRatenumber (decimal)Total cost for this rate plan across requested dates (0 if unavailable).
meta.filters.property_idstring (UUID)Echo of the requested property ID.
meta.filters.date.gtestring (YYYY-MM-DD)Echo of the start date (inclusive).
meta.filters.date.ltestring (YYYY-MM-DD)Echo of the end date (inclusive).