Flexible search (duration and dates)

  • Product Information
  • Shopping calendar
  • 2 routes
How do I explore bookable dates and durations before selecting a departure?

This scenario documents a flexible search journey that combines bookable dates and calendar inspection to help a user explore durations and date windows before selecting an exact departure.

Overview

The route sequence starts with GET/v1/products/{product_id}/bookable_dates to identify eligible dates and durations, then uses GET/v2/products/{product_id}/calendar to inspect the pricing calendar for the selected criteria.

Prerequisites

  • product_id must be known.
  • Date and duration filters may be required depending on the exploration mode.
  • accept-language and x-api-key are required on the documented calls.

Process workflow

Legend:
Mandatory
Optional
1

Explore bookable dates and durations

Mandatory

Use GET/v1/products/{product_id}/bookable_dates to discover which departure dates are bookable and which stay durations are available for each date before choosing a precise search context.

Prerequisites

  • Header accept-language
  • Header x-api-key
  • Optional header authorization
  • Path product_id
  • Optional query departure_option_id
  • Optional query first_date
  • Optional query last_date

Calling CURL

curl --get "https://api.clubmed.com/v1/products/MPAC/bookable_dates" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>" \
  --data-urlencode "first_date=2022-04-15" \
  --data-urlencode "last_date=2022-06-15"

Example answer

{
  "months": [
    {
      "id": 202001,
      "days": [
        {
          "id": 20200101,
          "availabilities": [
            {
              "status": "OPEN",
              "sibling_id": "CHAC_SUMMER",
              "durations": [7]
            }
          ]
        }
      ]
    }
  ]
}

info: This route is useful when the user is still flexible on both departure date and duration. Reuse the selected day and duration in the price calendar step.

Response codes

  • 200: bookable dates returned successfully.
  • 400: bad request or validation error.
  • 401: unauthorized when a protected context is requested.
  • 404: unknown product.
GET/v1/products/{product_id}/bookable_dates
See more
2

Inspect the calendar for selected criteria

Mandatory

Use GET/v2/products/{product_id}/calendar once the user has narrowed down the duration and traveller criteria returned by the flexible exploration step.

Prerequisites

  • Header accept-language
  • Header x-api-key
  • Optional header authorization
  • Path product_id
  • Required query duration
  • Optional query departure_option_id
  • Optional query number_attendees
  • Optional query birthdates
  • Optional query first_date
  • Optional query last_date

Calling CURL

curl --get "https://api.clubmed.com/v2/products/MPAC/calendar" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>" \
  --data-urlencode "duration=7" \
  --data-urlencode "number_attendees=2" \
  --data-urlencode "first_date=2022-04-15" \
  --data-urlencode "last_date=2022-06-15"

Example answer

{
  "months": [
    {
      "id": "201511",
      "days": [
        {
          "id": "20151129",
          "availability": "OPEN",
          "price": {
            "currency": "EUR"
          },
          "terms_and_conditions": {
            "duration": 7,
            "package": "AI",
            "departure_city": {
              "id": "PAR",
              "label": "Paris"
            }
          }
        }
      ]
    }
  ]
}

info: This step turns a flexible search into a price comparison view. Use the returned days to decide which departure date should feed the next proposal or booking step.

Response codes

  • 200: calendar returned successfully.
  • 400: missing duration, bad request or validation error.
  • 401: unauthorized when a protected context is requested.
  • 404: unknown product.
GET/v2/products/{product_id}/calendar
See more