{"openapi":"3.2.0","info":{"title":"Google Flights API","description":"Real-time flight search powered by Google Flights — one-way & round-trip fares, price calendar, and airport autocomplete.","version":"1.0.0"},"servers":[{"url":"https://google-flights.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Flights"},{"name":"System"},{"name":"Airports"},{"name":"openapi.json"}],"x-agent-commerce":{"catalog_url":"https://google-flights.jojapi.net/_jojapi/agent/plans","discovery_url":"https://google-flights.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/google-flights-api","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/v1/flights/calendar":{"get":{"operationId":"get_v1_flights_calendar","summary":"/v1/flights/calendar","description":"Cheapest fare per departure date across a range (max 30 days). For round trips, supply `tripLengthDays`. Note: this performs multiple upstream lookups, so it is slower than a single search.","tags":["Flights"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["from","to","currency","cheapest","days"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"currency":{"type":"string"},"cheapest":{"type":["object","null"],"properties":{"date":{"type":"string"},"price":{"type":"number"}}},"days":{"type":"array","items":{"type":"object","required":["date","price","currency"],"properties":{"date":{"type":"string"},"price":{"type":["number","null"]},"currency":{"type":"string"}}}}}},"examples":{"Example_1":{"value":{"from":"","to":"","currency":"","cheapest":{"date":"","price":0},"days":[{"date":"","price":0,"currency":""}]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error","message","statusCode"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"},"details":{}}},"examples":{"Example_1":{"value":{"error":"","message":"","statusCode":0}}}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error","message","statusCode"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"},"details":{}}},"examples":{"Example_1":{"value":{"error":"","message":"","statusCode":0}}}}}}},"parameters":[{"name":"currency","in":"query","required":true,"schema":{"type":"string","example":"USD","default":"USD"}},{"name":"tripLengthDays","in":"query","description":"For round trips: nights at destination","required":false,"schema":{"type":"number"}},{"name":"cabinClass","in":"query","description":"Cabin class","required":true,"schema":{"type":"string","enum":["economy","premium-economy","business","first"],"default":"economy"}},{"name":"locale","in":"query","required":true,"schema":{"type":"string","example":"en-US","default":"en-US"}},{"name":"country","in":"query","required":true,"schema":{"type":"string","example":"US","default":"US"}},{"name":"startDate","in":"query","description":"Range start date (YYYY-MM-DD)","required":true,"schema":{"type":"string","example":"2026-09-15"}},{"name":"to","in":"query","description":"Destination IATA airport code","required":true,"schema":{"type":"string","example":"LAX"}},{"name":"endDate","in":"query","description":"Range end date (YYYY-MM-DD)","required":true,"schema":{"type":"string","example":"2026-09-21"}},{"name":"from","in":"query","description":"Origin IATA airport code","required":true,"schema":{"type":"string","example":"JFK"}}]}},"/v1/flights/price-history":{"get":{"operationId":"get_v1_flights_price_history","summary":"/v1/flights/price-history","description":"Historical lowest prices observed for a route/date by this API over time. Requires Postgres persistence to be enabled; returns an empty series otherwise.","tags":["Flights"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["from","to","departDate","count","series"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"departDate":{"type":"string"},"count":{"type":"integer"},"series":{"type":"array","items":{"type":"object","required":["observedAt","lowestPrice"],"properties":{"observedAt":{"format":"date-time","type":"string"},"lowestPrice":{"type":"number"}}}}}},"examples":{"Example_1":{"value":{"from":"","to":"","departDate":"","count":0,"series":[{"observedAt":"","lowestPrice":0}]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error","message","statusCode"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"},"details":{}}},"examples":{"Example_1":{"value":{"error":"","message":"","statusCode":0}}}}}}},"parameters":[{"name":"departDate","in":"query","description":"Departure date (YYYY-MM-DD)","required":true,"schema":{"type":"string","example":"2026-09-15"}},{"name":"to","in":"query","description":"Destination IATA airport code","required":true,"schema":{"type":"string","example":"LAX"}},{"name":"from","in":"query","description":"Origin IATA airport code","required":true,"schema":{"type":"string","example":"JFK"}},{"name":"limit","in":"query","required":true,"schema":{"type":"number","example":50,"default":50}}]}},"/v1/flights/search":{"get":{"operationId":"get_v1_flights_search","summary":"/v1/flights/search","description":"Returns live itineraries from Google Flights for a one-way or round-trip route. Results are cached server-side; pass `refresh=true` to force a live fetch.","tags":["Flights"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["currency","lowestPrice","source","fetchedAt","resultCount","itineraries"],"properties":{"currency":{"type":"string"},"lowestPrice":{"type":["number","null"]},"source":{"type":"string","enum":["live","cache"]},"fetchedAt":{"format":"date-time","type":"string"},"resultCount":{"type":"integer"},"itineraries":{"type":"array","items":{"type":"object","required":["airlines","price","currency","departureTime","arrivalTime","arrivalDayOffset","departureAirport","arrivalAirport","durationMinutes","durationLabel","stops","stopAirports","co2Kg","priceLevel","selfTransfer"],"properties":{"airlines":{"description":"Operating carrier(s)","type":"array","items":{"type":"string"}},"price":{"type":["number","null"]},"currency":{"type":"string"},"departureTime":{"type":["string","null"]},"arrivalTime":{"type":["string","null"]},"arrivalDayOffset":{"description":"Days arrival is offset from departure","type":"integer"},"departureAirport":{"type":["string","null"]},"arrivalAirport":{"type":["string","null"]},"durationMinutes":{"type":["integer","null"]},"durationLabel":{"type":["string","null"]},"stops":{"description":"0 = nonstop","type":"integer"},"stopAirports":{"type":"array","items":{"type":"string"}},"co2Kg":{"type":["integer","null"]},"priceLevel":{"type":["string","null"],"enum":["low","typical","high",null],"description":"Google's overall price assessment"},"selfTransfer":{"type":"boolean"}}}}}},"examples":{"Example_1":{"value":{"currency":"","lowestPrice":0,"source":"live","fetchedAt":"","resultCount":0,"itineraries":[{"airlines":[],"price":0,"currency":"","departureTime":"7:35 PM","arrivalTime":"10:49 PM","arrivalDayOffset":0,"departureAirport":"","arrivalAirport":"","durationMinutes":0,"durationLabel":"6 hr 14 min","stops":0,"stopAirports":[],"co2Kg":0,"priceLevel":"low","selfTransfer":true}]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error","message","statusCode"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"},"details":{}}},"examples":{"Example_1":{"value":{"error":"","message":"","statusCode":0}}}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error","message","statusCode"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"},"details":{}}},"examples":{"Example_1":{"value":{"error":"","message":"","statusCode":0}}}}}}},"parameters":[{"name":"sort","in":"query","description":"Result ordering","required":true,"schema":{"type":"string","enum":["best","price","duration","departure","arrival"],"default":"best"}},{"name":"refresh","in":"query","description":"Bypass cache and force a live fetch","required":true,"schema":{"type":"boolean","example":false,"default":false}},{"name":"from","in":"query","description":"Origin IATA airport code","required":true,"schema":{"type":"string","example":"JFK"}},{"name":"currency","in":"query","description":"ISO 4217 currency code","required":true,"schema":{"type":"string","example":"USD","default":"USD"}},{"name":"children","in":"query","required":true,"schema":{"type":"number","example":0,"default":0}},{"name":"returnDate","in":"query","description":"Return date (YYYY-MM-DD). Presence makes the search round-trip.","required":false,"schema":{"type":"string"}},{"name":"maxResults","in":"query","required":true,"schema":{"type":"number","example":50,"default":50}},{"name":"departDate","in":"query","description":"Departure date (YYYY-MM-DD)","required":true,"schema":{"type":"string","example":"2026-09-15"}},{"name":"infantsInSeat","in":"query","required":true,"schema":{"type":"number","example":0,"default":0}},{"name":"locale","in":"query","description":"BCP-47 locale for results","required":true,"schema":{"type":"string","example":"en-US","default":"en-US"}},{"name":"to","in":"query","description":"Destination IATA airport code","required":true,"schema":{"type":"string","example":"LAX"}},{"name":"adults","in":"query","required":true,"schema":{"type":"number","example":1,"default":1}},{"name":"stops","in":"query","description":"Maximum number of stops (any, 0=nonstop, 1, 2)","required":true,"schema":{"type":"string","enum":["any","0","1","2"],"default":"any"}},{"name":"country","in":"query","description":"ISO 3166-1 country for pricing/market","required":true,"schema":{"type":"string","example":"US","default":"US"}},{"name":"cabinClass","in":"query","description":"Cabin class","required":true,"schema":{"type":"string","enum":["economy","premium-economy","business","first"],"default":"economy"}},{"name":"infantsOnLap","in":"query","required":true,"schema":{"type":"number","example":0,"default":0}}]}},"/health":{"get":{"operationId":"get_health","summary":"/health","description":"Check service health","tags":["System"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status","uptimeSeconds","cache","database","airports","version"],"properties":{"status":{"type":"string"},"uptimeSeconds":{"type":"number"},"cache":{"type":"string"},"database":{"type":"string"},"airports":{"type":"integer"},"version":{"type":"string"}}},"examples":{"Example_1":{"value":{"status":"","uptimeSeconds":0,"cache":"","database":"","airports":0,"version":""}}}}}}}}},"/v1/airports/search":{"get":{"operationId":"get_v1_airports_search","summary":"/v1/airports/search","description":"Search airports by IATA code, city or name. Backed by a bundled dataset — fast and free (does not count against upstream rate limits).","tags":["Airports"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["iata","name","city","country","lat","lon"],"properties":{"iata":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}}}}}},"examples":{"Example_1":{"value":{"count":0,"results":[{"iata":"","name":"","city":"","country":"","lat":0,"lon":0}]}}}}}}},"parameters":[{"name":"limit","in":"query","required":true,"schema":{"type":"number","example":10,"default":10}},{"name":"q","in":"query","description":"Search by IATA code, city or airport name","required":true,"schema":{"type":"string","example":"New York"}}]}},"/openapi.json":{"get":{"operationId":"get_openapi_json","summary":"/openapi.json","description":"Service OpenAPI Spec","tags":["openapi.json"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"examples":{"Example_1":{"value":{}}}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}