Step 5: Shallow & deep availability searches – Bókun developer documentation

In order to become bookable, a product has to be created, published and mapped first. All of this has been described in the previous chapters. The next very important step in the process of bookability is the availability check.

If Channel manager plugin has SUPPORTS_AVAILABILITY capability, availability will be fetched from the plugin; otherwise availability will be managed in Bókun silos.

There are two availability search patterns in Bókun:

“Shallow” search, where the end user intention is to find a list of products for given number of passengers for given date range for given location, e.g. “3 PAX city guide in Reykjavik on 2nd of October 2017”. This search only yields basic information, responding with which products are available upon given query.

“Deep” search where one particular product (of returned list above) is selected and query is made to discover available times (if applicable), capacity, prices, rates and so on. Providing the result of this call is satisfactory, the end user is ready to make a booking decision.

gRPC service interfaces

gRPC-enabled plugins must implement the following API calls:

rpc GetAvailableProducts(ProductsAvailabilityRequest) returns (stream ExternalProductId) {}

The above call (further referred as shallow availability search) returns a subset of products meeting the search criteria.

rpc GetProductAvailability(ProductAvailabilityRequest) returns (stream io.bokun.inventory.common.api.grpc.ProductAvailabilityWithRatesResponse) {}

The above call (further referred as deep availability search) returns extensive information about the availability of a single product.

REST URLs

REST-enabled plugins must provide valid responses on the following URLs:

POST /product/getAvailable

The above call (further referred as shallow availability search) should return a subset of products meeting the search criteria.

POST /product/getAvailability

The above call (further referred as deep availability search) should extensive information about the availability of a single product.

Shallow availability call

Shallow availability call is used in early stages of the booking process when the precise details (such as exact date or even the desired product) might not yet be known.

In the above pictured case, only one product is available given search criteria, however there might as well be more. Product selection happens (in this case) by clicking on a particular product, where availability calendar is shown. This is where deep search comes in.

Shallow call sends ProductsAvailabilityRequest which contains search criteria and expects a collection of ProductsAvailabilityResponses back.

The structure of ProductsAvailabilityRequest is as follows:

Attribute	Mandatory	Notes
parameters	✓	Plugin configuration parameters, as specified in Step 3. plugin configuration
range	✓	Range of dates [`from`..`to`] for which the experience is sought
requiredCapacity	✓	How many passengers are going to travel? If the value is 0, the capacity is not known. Otherwise the value is guaranteed to be a positive integer
externalProductIds	✓	Provides a list of products (or, rather, their ids) to search within. The list is never empty and can only contain mapped product ids

The structure of each ProductsAvailabilityResponse is as follows:

Attribute	Mandatory	Notes
productId	✓	Id of product if it is available for given criteria. Must refer to any of the entries in `ProductsAvailabilityRequest::externalProductIds`
actualCheckDone		Whether the actual availability check was done. Some APIs might not support checking for multiple product availability over date range (instead they typically support checking availability of one product and sometimes - for a very limited range only). As a workaround for this problem, plugin might return fake availability response and then next step will clarify that. For fake responses, this should be set to false.

Deep availability call

Deep availability is used for a number of purposes, including:

Fill the calendar with available dates

Specify which start times, pricing categories, rates and so on are available and at what price

Information elements from the deep availability response will be used to create a booking.

Deep availability call sends ProductAvailabilityRequest which contains search criteria and expects a collection of ProductAvailabilityWithRatesResponse back.

The structure of ProductAvailabilityRequest is as follows:

Attribute	Mandatory	Notes
parameters	✓	Plugin configuration parameters, as specified in Step 3. plugin configuration
productId	✓	Product id on external system for which the deep availability is queried
range	✓	Date range (boundaries included) for which we want to know precise capacity, availability and pricing for given product. Note that this request does not ask for capacity; instead response should tell us how much seats/spaces/etc are available in total

Each different date/time slot must be responded with a separate object. If there is no availability on a given date/time, relevant object should be omitted from sending back (as opposed to sending back object with zero capacity).

IMPORTANT: in case each rate has distinct ProductAvailabilityWithRatesResponse element in the response, start times in Bokun platform should be assigned to that distinct rate separately. E.g. if you have several rates, which are operated at the same start time, in Bokun platform should be created duplicate start times and assigned to each rate separately.

The structure of ProductAvailabilityWithRatesResponse is as follows:

Attribute	Mandatory	Notes
capacity	✓	How many slots are available for this date (and time, if support)
date	✓	Date for when this product is available.
time	see notes	When does this product start? Unset if this product does not support start time.
pickupTime	see notes	When does the pick up for this product start? Unset if this product does not support start time or pickups.
rates	✓	A collection of rates with prices applicable for this date/time slot. Mandatory; should at least have a single entry.

Please note that Bókun API supports availability requests for the date range of a full year. Therefore, it is expected that the same rule is applied to the plugin behaviour.

In case plugin does not support responding with availabilities for the range of up to full year, it is supplier’s obligation solely to inform their selling partners on this limitation.