3 · Available dates

List available dates for a route.

What: the departure dates the suppliers’ own catalogues list for an origin → destination. A listed date is what the supplier publishes, not a promise of a seat: search the date to see fares.

When: to build a date picker / calendar before searching.

How: POST with a JSON body { origin, destination, tripType? }. No query params.

Response: { origin, destination, tripType, dates[] } — the route + trip kind are echoed ONCE (they are the request body inputs), with the bookable dates listed under them. meta.count = number of dates.

• No tripType sent (every kind): tripType is null; one row per date, sorted, each { departureDate, tripTypes } — the kinds the catalogues list for that day, ONE_WAY first. ["ROUND_TRIP"] alone means only round-trip packages were listed for that day (a one-way supplier that failed is reported in meta.suppliers). Round-trip dates are asked only of suppliers that sell round-trip packages.
• tripType sent: only that kind, { departureDate } per date, and no tripTypes.
• No return dates: a date is the day a trip LEAVES. Packages leaving the same day can come back on different days, so /search names each package with its own returnDate.

Gotcha: this returns dates only — no prices or seats. Call /search for offers + prices. sources works as on /origins.

Supplier health: meta.suppliers[] has one entry per supplier Kitionz considered, for each trip kind it was asked about: { sourceCode, tripType, status, tookMs }. With no tripType in the request, a supplier that sells round trips has two entries (ONE_WAY and ROUND_TRIP). status = ok, not_asked, or a classified error code. not_asked (with reason = ORIGIN_NOT_LISTED or DEST_NOT_LISTED) means the supplier was not called because its own saved list for the previous step did not contain the airport — an answer, not a fault; treat only error codes as failures, and treat an unrecognised status as opaque. If a supplier fails (or is backing off after rate-limiting Kitionz) and Kitionz holds a recent good answer from it, that answer is still included and its entry carries stale: true + staleAgeMs (route lists up to 24 h old, date lists up to 2 h old with past dates removed). Route lists are cached for up to 2 h and date lists for up to 15 min: a list is served from the cache inside its window and fetched again on the first request after it.

Example — request (every trip kind):

{ "origin": "DEL", "destination": "BOM" }

Response (trimmed) — 15 Jan has one-way flights only; on 16 Jan a round-trip package leaves too:

{ "data": { "origin": { "iataCode": "DEL" }, "destination": { "iataCode": "BOM" }, "tripType": null, "dates": [ { "departureDate": "2027-01-15", "tripTypes": ["ONE_WAY"] }, { "departureDate": "2027-01-16", "tripTypes": ["ONE_WAY", "ROUND_TRIP"] } ] }, "meta": { "count": 2 } }