Availability

A Supplier defines the available times or time slots and dates for a tour or attraction, as well as the number of customers that can be booked.

• FREESALE: Tickets and entry passes are available during the opening hours of the attraction, and there is generally no limit on the number of tickets.
• RESERVED: Rates can be with or without capacity, depending on the requirements and inventory defined by the Supplier.

Whenever a Reseller requests the availability of Products or Rates bound to their channel, Travel Curious returns this data from the Travel Curious Availability Cache.

Traveler Type Availability (granularity parameter)

The Reseller API accepts a query parameter called granularity, which allows you to define how availability data is grouped. It accepts two values: travelerType or rate.

1. **granularity=travelerType**

If this value is passed, the availability data is broken down specifically at the ageBand level. This is useful if a Supplier has distinct capacity limits for different guest types.

xxxxxxxxxx

{

    "availability": [

        {

            "capacity": 19,

            "end": "2026-08-17T00:15:00Z",

            "id": "472239-20260816-2000",

            "maxCapacity": -1,

            "start": "2026-08-17T00:00:00Z",

            "unit_id": "472240"

        },

        {

            "capacity": 19,

            "end": "2026-08-17T00:15:00Z",

            "id": "472239-20260816-2000",

            "maxCapacity": -1,

            "start": "2026-08-17T00:00:00Z",

            "unit_id": "472241"

        }

    ]

}

2. `granularity=rate` (Default Behavior)

If the query parameter is absent or set to rate, any ageBand-level availability will be rolled up into a single rate-level availability block.

How the Roll-up Works:

• The system locates any ageBand-level availability within a given time slot.
• It finds the one with the smallest capacity number and replaces all ageBand-level availabilities with a single object using that smallest capacity.
• The rolled-up availability is assigned a special ID with a GENERATED-ID: prefix.
• The object will contain an extension key that links the original unit IDs to the newly generated availability ID.

xxxxxxxxxx

{

    "availability": [

        {

            "capacity": 19,

            "end": "2023-08-17T00:15:00Z",

            "extensions": {

                "unit:472240": "472239-20230816-2000",

                "unit:472241": "472239-20230816-2000"

            },

            "id": "GENERATED-ID:f47fc8b4-62ac-4868-93a4-862630ae5994",

            "maxCapacity": -1,

            "start": "2023-08-17T00:00:00Z"

        }

    ]

}

The Travel Curious Availability Cache

To ensure high performance, the Travel Curious Availability Cache serves two primary functions:

1. Guarantee an API response time of under 2 seconds.
2. Decrease network traffic and load on Supplier reservation systems.

Travel Curious pulls bound Product and Rate availability from connected Suppliers based on their schedules and stores it in the cache.

Cache Transaction Logic

When an availability request is made, the system follows a strict performance protocol to ensure you receive a fast response:

1. Cache Check: The system checks if data exists in the cache. If empty, it returns no availabilities.

2. Freshness Check (< 5 Minutes): If the cached data is less than 5 minutes old, it is returned immediately to the Reseller.

3. Stale Cache & The 2-Second Rule: If the cached data is older than 5 minutes, Travel Curious attempts to fetch fresh data from the Supplier's Reservation System.

   • If the Supplier responds within 2 seconds: The new availability data is returned to you and cached for future requests.
   • If the Supplier takes longer than 2 seconds: To protect your application's performance, the API will abort the live wait and instantly return the older cached availability. The cache will then quietly populate in the background once the Supplier finally responds.

Transaction Flow Diagram