Search flights between a known origin and destination for flexible dates
curl --request POST \
--url https://api.gojinko.com/v1/flight_calendar \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"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"
}
'import requests
url = "https://api.gojinko.com/v1/flight_calendar"
payload = {
"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"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.gojinko.com/v1/flight_calendar', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/flight_calendar",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/flight_calendar"
payload := strings.NewReader("{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/flight_calendar")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/flight_calendar")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"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",
"stops": 0,
"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",
"stops": 0,
"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=="
}{
"error": {
"code": "BAD_REQUEST",
"message": "Malformed JSON in request body.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "CONFLICT",
"message": "The operation conflicts with the current state of the resource.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "A required field is missing or invalid.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}Discovery
flight-calendar
Search flights between a known origin and destination for flexible dates
POST
/
v1
/
flight_calendar
Search flights between a known origin and destination for flexible dates
curl --request POST \
--url https://api.gojinko.com/v1/flight_calendar \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"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"
}
'import requests
url = "https://api.gojinko.com/v1/flight_calendar"
payload = {
"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"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.gojinko.com/v1/flight_calendar', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/flight_calendar",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/flight_calendar"
payload := strings.NewReader("{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/flight_calendar")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/flight_calendar")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"origins\": [\n \"NYC\"\n ],\n \"destinations\": [\n \"PAR\"\n ],\n \"trip_type\": \"roundtrip\",\n \"departure_date_ranges\": [\n {\n \"start\": \"2026-09-01\",\n \"end\": \"2026-09-30\"\n }\n ],\n \"stay_days\": 7,\n \"cabin_class\": \"economy\",\n \"currency\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"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",
"stops": 0,
"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",
"stops": 0,
"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=="
}{
"error": {
"code": "BAD_REQUEST",
"message": "Malformed JSON in request body.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "CONFLICT",
"message": "The operation conflicts with the current state of the resource.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "A required field is missing or invalid.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}Find priced itineraries between a known origin and destination using cached results, ideal when the user is flexible on dates. It answers questions like “cheapest week to fly Paris to Barcelona in June” or “best Friday to Sunday options from JFK to LAX next month”. Each itinerary’s
id is its offer token: pass that id as offer_token to flight_search for live pricing. The REST response has no field named offer_token. Add the selected live fare’s trip_item_token to a trip.
Prices are in minor units.
value is an integer — divide by
10 ** decimal_places to display it. { "value": 15977, "decimal_places": 2 }
is $159.77, not $15,977. See Money & prices.Authorizations
ApiKeyAuthBearerAuth
Body
application/json
IATA city or airport codes. See origin_type for how an untyped code is read.
Minimum array length:
1Example:
["NYC"]
Available options:
oneway, roundtrip Example:
"roundtrip"
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.
Example:
["PAR"]
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.
Available options:
city, airport Example:
"city"
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.
Available options:
city, airport Example:
"city"
Pattern:
^\d{4}-\d{2}-\d{2}$Example:
["2026-07-15"]
Show child attributes
Show child attributes
Pattern:
^\d{4}-\d{2}-\d{2}$Example:
["2026-07-22"]
Show child attributes
Show child attributes
Required range:
x > 0Example:
7
Show child attributes
Show child attributes
Available options:
economy, premium_economy, business, first Example:
"economy"
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.
Example:
false
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.
Available options:
standard, high Example:
"standard"
Caps the cached fare's total. Cached fares are priced for one adult.
Required range:
x > 0Example:
800
Example:
"USD"
Example:
"en-US"
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.
Required range:
1 <= x <= 100Required range:
x >= 0Available options:
lowest, recommendation Show child attributes
Show child attributes
Response
Matching itineraries
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.
Available options:
one_adult Example:
"one_adult"
Show child attributes
Show child attributes
Example:
"eyJvZmZzZXQiOjIwfQ=="