--- title: "Cheapest fares for a fixed route + date — up to ten itineraries, cheapest first" method: POST path: "/v1/lowest_fare" tags: ["Discovery"] --- # Cheapest fares for a fixed route + date — up to ten itineraries, cheapest first `POST /v1/lowest_fare` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/lowest_fare` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Takes the same request as flight_calendar but, for a fixed origin, destination, and date, returns up to ten itineraries sorted cheapest-first; `limit` is not applied on this route. The fixed-date counterpart of flight_calendar. Cache-backed; never live-prices. ## Request body - FlightDiscoveryRequest - `origins` string[], required: IATA city or airport codes. See `origin_type` for how an untyped code is read. - `destinations` string[]: 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': 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. - `departure_dates` string[] - `departure_date_ranges` DateRange[] - `start` string, required - `end` string, required - `return_dates` string[] - `return_date_ranges` DateRange[] - `start` string, required - `end` string, required - `stay_days` integer - `stay_days_range` object - `min` integer, required - `max` integer, required - `trip_type` 'oneway' | 'roundtrip', required - `cabin_class` 'economy' | 'premium_economy' | 'business' | 'first' - `direct_only` boolean: 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_total` number: Caps the cached fare's total. Cached fares are priced for one adult. - `currency` string - `locale` string - `limit` integer: 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. - `offset` integer - `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. - `intent` IntentInput - `user_intent` string, nullable: The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. ## Response `200` Cheapest itineraries for the route + date, lowest-first - FlightCalendarResponse - `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`. - `itineraries` Itinerary[], required - `offer_token` string, required: This cached itinerary’s offer token: pass it unchanged as `offer_token` to `POST /v1/flight_search` to price-check it live. It cannot be added to a trip. - `id` string, required: Deprecated: use `offer_token` instead. Same value. - `origin` object, required - `code` string, required - `name` string - `destination` object, required - `code` string, required - `name` string - `total` object: One adult's fare (`priced_for: "one_adult"`): the cache holds one-adult fares only. To price the whole party, pass `offer_token` to `POST /v1/flight_search` with the party. - `value` integer, required: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `cabin_class` string - `outbound` object: The outbound journey this price is for — the departure date and time are in `departure_datetime`. Absent on cached rows stored before the platform kept the flown itinerary. - `origin` string - `destination` string - `departure_datetime` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `arrival_datetime` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `duration_minutes` number - `airline` string - `airline_name` string - `stops` number - `stop_infos` StopInfo[]: Layover detail, one entry per stop, in travel order. Absent when the leg is non-stop (`stops: 0`) or when upstream detail is incomplete for any stop; `stops` still reports the connection count in that case. - `airport_code` string: IATA code of the airport where the leg stops. - `duration_minutes` number: Layover length in minutes (arrival of the inbound segment to departure of the next). Omitted when the upstream times cannot be resolved. - `segments` CachedSegment[]: The flown segments of this leg, in travel order — one per flight. A non-stop leg has one. Read `operating_carrier` here to disclose a codeshare the cached fare recorded. Absent when the cached row has no segment breakdown, in which case `stops` and `stop_infos` are all that is known about the leg. - `airline` string: IATA code of the MARKETING carrier — whose flight number you booked. - `airline_name` string - `flight_number` string: Provider flight number, forwarded unchanged. Depending on the upstream provider it may be a bare number such as `460` or a composed designator such as `AS460`; the carrier code is also carried separately when known. - `departure_airport` string - `departure_city` string - `departure_time` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `arrival_airport` string - `arrival_city` string - `arrival_time` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `duration_minutes` number - `layover_minutes` number: Wait between this segment’s arrival and the next departure. Absent on the last segment of a leg, and whenever the upstream times could not be resolved. - `operating_carrier` string: IATA code of the carrier that actually OPERATES the segment, when the cached fare recorded one. A value differing from `airline` is a codeshare the passenger must be told about. Equality is not guaranteed to be stated: the field is absent when the cached record carries no operating carrier, which says nothing about who operates the flight. - `inbound` object: The return journey. Present on a round trip only, and absent on an older cached row the same way `outbound` is. - `origin` string - `destination` string - `departure_datetime` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `arrival_datetime` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `duration_minutes` number - `airline` string - `airline_name` string - `stops` number - `stop_infos` StopInfo[]: Layover detail, one entry per stop, in travel order. Absent when the leg is non-stop (`stops: 0`) or when upstream detail is incomplete for any stop; `stops` still reports the connection count in that case. - `airport_code` string: IATA code of the airport where the leg stops. - `duration_minutes` number: Layover length in minutes (arrival of the inbound segment to departure of the next). Omitted when the upstream times cannot be resolved. - `segments` CachedSegment[]: The flown segments of this leg, in travel order — one per flight. A non-stop leg has one. Read `operating_carrier` here to disclose a codeshare the cached fare recorded. Absent when the cached row has no segment breakdown, in which case `stops` and `stop_infos` are all that is known about the leg. - `airline` string: IATA code of the MARKETING carrier — whose flight number you booked. - `airline_name` string - `flight_number` string: Provider flight number, forwarded unchanged. Depending on the upstream provider it may be a bare number such as `460` or a composed designator such as `AS460`; the carrier code is also carried separately when known. - `departure_airport` string - `departure_city` string - `departure_time` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `arrival_airport` string - `arrival_city` string - `arrival_time` string: Local time at the airport, RFC 3339 with that airport’s UTC offset (e.g. `2026-09-23T11:55:00-04:00`). Parse it as an instant; do not assume UTC and do not compare two of these as strings. On the rare airport whose timezone the platform does not know, a cached time keeps its local wall-clock digits but is written as UTC (`…Z`), so it reads as an instant that is off by that airport’s true offset; the offset is never omitted here, unlike on a live leg. The `*_local` fields of a booked or exchanged itinerary are NOT this: those carry wall-clock time with no offset, by design. - `duration_minutes` number - `layover_minutes` number: Wait between this segment’s arrival and the next departure. Absent on the last segment of a leg, and whenever the upstream times could not be resolved. - `operating_carrier` string: IATA code of the carrier that actually OPERATES the segment, when the cached fare recorded one. A value differing from `airline` is a codeshare the passenger must be told about. Equality is not guaranteed to be stated: the field is absent when the cached record carries no operating carrier, which says nothing about who operates the flight. - `priced_at` string: When this price was collected, RFC 3339 UTC. These results come from the cache and can be days old — re-price with `flight_search` before quoting or booking. - `next_page_token` string ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Resource not found - `409`: The operation conflicts with the current state of the resource - `410`: The resource this request names no longer exists - `422`: Validation error - `429`: Rate limit or quota exceeded - `502`: The travel provider rejected the request, or an upstream call failed - `503`: No travel provider can serve the request right now - `504`: The travel provider did not answer in time --- [API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)