Discovery

Best date options for a route — the cheapest itinerary per date pair, spread across the window

Takes the same request as flight_calendar and returns one cheapest itinerary per (departure, return) date pair, for up to limit date pairs (default 20) spread across the requested departure window, so you see a diverse set of date options rather than near-adjacent cheapest days. Cache-backed; never live-prices.

post/v1/find_dates

Request

Base URL
https://api.gojinko.com
URL
https://api.gojinko.com/v1/find_dates
Auth
- API key in header X-API-Key
- or HTTP bearer

Request body

originsstring[] required

IATA city or airport codes. See origin_type for how an untyped code is read.

destinationsstring[]

IATA city or airport codes. Omit for global discovery (find_destination) or to scan every destination from the origins. See destination_type for how an untyped code is read.

origin_type'city' | 'airport'

How to read the code: city searches every airport of the city, airport only that one airport. Omit it and the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. Untyped NYC, LON or PAR is the city; untyped JFK, LHR or CDG is the airport; and untyped LAX, MIA or LAS — codes a city shares with its main airport — is the CITY, so results can land at any airport of that city. If the user named the airport, send airport; if they named the city, omit the field.

destination_type'city' | 'airport'

departure_datesstring[]

return_datesstring[]

stay_daysinteger

trip_type'oneway' | 'roundtrip' required

cabin_class'economy' | 'premium_economy' | 'business' | 'first'

direct_onlyboolean

Only direct flights. Cached fares record whether a fare is direct but not how many stops it makes, so this is the only stop filter here; POST /v1/flight_search takes max_stops.

accuracy'standard' | 'high'

How strict the freshness check on cached fares is. standard (default) returns fares estimated to be at least 80% likely to still be available at the cached price; high raises that to 95%, so fewer fares come back.

max_totalnumber

Caps the cached fare's total. Cached fares are priced for one adult.

currencystring

localestring

limitinteger

What limit counts depends on the route; 1 to 100, default 20. On flight_calendar, the maximum number of itineraries returned across the entire matching date range after sort_by is applied. This is a global result cap, not one itinerary per date pair: with the default sort_by: lowest, limit: N returns the cheapest N itineraries overall, so some matching date pairs may be absent. On find_dates, the maximum number of date pairs, each answered with its cheapest itinerary and spread across the requested departure window. On lowest_fare, not applied: that route returns at most ten itineraries, cheapest first.

offsetinteger

sort_by'lowest'

The order of the results. lowest, the only order today, is cheapest first by the cached one-adult total; on find_destination it orders destinations by their cheapest itinerary. Omit it for the same order.

Example request

{
  "origins": [
    "NYC"
  ],
  "destinations": [
    "PAR"
  ],
  "trip_type": "roundtrip",
  "departure_date_ranges": [
    {
      "start": "2026-09-01",
      "end": "2026-09-30"
    }
  ],
  "stay_days": 7,
  "cabin_class": "economy",
  "currency": "USD"
}

Response

Best date options (one itinerary per date-pair)

priced_for'one_adult' required

Whose price the cached fares in this answer are: always one_adult. Every cached total is one adult's fare; this request takes no passenger counts. Price the whole party with POST /v1/flight_search.

next_page_tokenstring

Example response

{
  "priced_for": "one_adult",
  "itineraries": [
    {
      "offer_token": "es-VVN8QUZ8MjAyNzA2MTU6QUY6Nzo6WXwyMDI3MDYyMjpBRjo2OjpZ",
      "id": "es-VVN8QUZ8MjAyNzA2MTU6QUY6Nzo6WXwyMDI3MDYyMjpBRjo2OjpZ",
      "origin": {
        "code": "JFK",
        "name": "New York John F. Kennedy"
      },
      "destination": {
        "code": "CDG",
        "name": "Paris Charles de Gaulle"
      },
      "total": {
        "value": 41250,
        "currency": "USD",
        "decimal_places": 2,
        "display": "USD 412.50"
      },
      "cabin_class": "economy",
      "outbound": {
        "origin": "JFK",
        "destination": "LAX",
        "departure_datetime": "2026-07-15T08:30:00-04:00",
        "arrival_datetime": "2026-07-15T11:55:00-07:00",
        "duration_minutes": 385,
        "airline": "AA",
        "airline_name": "American Airlines",
        "stop_infos": [
          {
            "airport_code": "DFW",
            "duration_minutes": 95
          }
        ],
        "segments": [
          {
            "airline": "AA",
            "airline_name": "American Airlines",
            "flight_number": "460",
            "departure_airport": "JFK",
            "departure_city": "New York",
            "departure_time": "2026-09-23T11:55:00-04:00",
            "arrival_airport": "DFW",
            "arrival_city": "Dallas",
            "arrival_time": "2026-09-23T15:10:00-05:00",
            "duration_minutes": 255,
            "layover_minutes": 95,
            "operating_carrier": "MQ"
          }
        ]
      },
      "inbound": {
        "origin": "JFK",
        "destination": "LAX",
        "departure_datetime": "2026-07-15T08:30:00-04:00",
        "arrival_datetime": "2026-07-15T11:55:00-07:00",
        "duration_minutes": 385,
        "airline": "AA",
        "airline_name": "American Airlines",
        "stop_infos": [
          {
            "airport_code": "DFW",
            "duration_minutes": 95
          }
        ],
        "segments": [
          {
            "airline": "AA",
            "airline_name": "American Airlines",
            "flight_number": "460",
            "departure_airport": "JFK",
            "departure_city": "New York",
            "departure_time": "2026-09-23T11:55:00-04:00",
            "arrival_airport": "DFW",
            "arrival_city": "Dallas",
            "arrival_time": "2026-09-23T15:10:00-05:00",
            "duration_minutes": 255,
            "layover_minutes": 95,
            "operating_carrier": "MQ"
          }
        ]
      },
      "priced_at": "2026-09-19T03:57:25Z"
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjIwfQ=="
}

Changes

No recorded changes to this operation across all 1 revision of this API.