Flight API endpoints

Search flights

POST /api/flights/serp/search

Search for flight offers using SerpAPI integration with Google Flights data.

Request

Authentication: None required (internal API) Headers:

Content-Type: application/json

Body parameters:

slices

array

Array of flight slices (up to 6). Either provide this or origin, destination, and departure_date.

Show Slice object

origin

string

required

3-letter IATA airport code (e.g., “JFK”)

destination

string

required

3-letter IATA airport code (e.g., “LAX”)

departure_date

string

required

Departure date in YYYY-MM-DD format

origin

string

3-letter IATA airport code for one-way or round-trip search

destination

string

3-letter IATA airport code for one-way or round-trip search

departure_date

string

Departure date in YYYY-MM-DD format

return_date

string

Return date in YYYY-MM-DD format (for round-trip)

adults

number

default:"1"

Number of adult passengers (1-10)

cabin_class

string

Cabin class preference

Response

boolean

required

Indicates if the request was successful

offers

array

Array of flight offers

Show FlightOffer object

string

Unique offer identifier

totalAmount

string

Total price amount

totalCurrency

string

Currency code (e.g., “USD”)

owner

object

Show Airline info

name

string

Airline name

iataCode

string

Airline IATA code

bookUrl

string

Direct booking URL (Google Flights)

bookingToken

string

SerpAPI booking token for resolving direct booking links

departureToken

string

Token for fetching return flight options

slices

array

Flight slices (outbound, return)

expiresAt

string

Offer expiration timestamp

error

string

Error message if ok is false

Example request

curl -X POST http://localhost:8080/api/flights/serp/search \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "JFK",
    "destination": "LAX",
    "departure_date": "2026-04-15",
    "return_date": "2026-04-22",
    "adults": 2
  }'

Example response

{
  "ok": true,
  "offers": [
    {
      "id": "serp-0-WyJbWyJKRktcIixcIjIwMjYtMDQtMTVcIixcIkxBWFwiLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGxdXSJd",
      "totalAmount": "298",
      "totalCurrency": "USD",
      "owner": {
        "name": "Delta",
        "iataCode": ""
      },
      "bookUrl": "https://www.google.com/travel/flights?hl=en&departure_id=JFK&arrival_id=LAX&outbound_date=2026-04-15&return_date=2026-04-22&type=1",
      "departureToken": "WyJbWyJKRktcIixcIjIwMjYtMDQtMTVcIixcIkxBWFwiLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGwsbnVsbCxudWxsLG51bGxdXSJd",
      "slices": [
        {
          "origin": {
            "name": "John F. Kennedy International Airport",
            "iataCode": "JFK"
          },
          "destination": {
            "name": "Los Angeles International Airport",
            "iataCode": "LAX"
          },
          "duration": "6h 15m",
          "segments": [
            {
              "operatingCarrier": {
                "name": "Delta",
                "iataCode": ""
              },
              "marketingCarrier": {
                "name": "Delta",
                "iataCode": ""
              },
              "flightNumber": "DL123",
              "departingAt": "2026-04-15T08:00:00-04:00",
              "arrivingAt": "2026-04-15T11:15:00-07:00",
              "origin": {
                "name": "John F. Kennedy International Airport",
                "iataCode": "JFK"
              },
              "destination": {
                "name": "Los Angeles International Airport",
                "iataCode": "LAX"
              },
              "duration": "6h 15m"
            }
          ]
        }
      ],
      "expiresAt": ""
    }
  ]
}

Error responses

boolean

false when error occurs

error

string

Error description

Status codes:

400 - Invalid request body or parameters
503 - SerpAPI key not configured
502 - SerpAPI service error
500 - Internal server error

Get booking options

POST /api/flights/serp/booking-options

Resolve SerpAPI booking token to direct booking URL and POST data.

Request

Authentication: None required (internal API) Body parameters:

booking_token

string

SerpAPI booking token from search results

departure_token

string

SerpAPI departure token (alternative to booking_token)

Provide either booking_token or departure_token.

Response

boolean

required

Request success status

url

string

Direct booking URL

post_data

string | null

POST data for booking form submission

Example request

curl -X POST http://localhost:8080/api/flights/serp/booking-options \
  -H "Content-Type: application/json" \
  -d '{
    "booking_token": "WyJbWyJKRktcIixcIjIwMjYtMDQtMTVcIixcIkxBWFwiXV0i"
  }'

Example response

{
  "ok": true,
  "url": "https://www.google.com/travel/flights/booking?...",
  "post_data": null
}

Error responses

Status codes:

400 - Missing token or invalid request
404 - No booking option available
503 - SerpAPI key not configured
502 - SerpAPI service error

Explore destinations

POST /api/flights/serp/explore

Find cheapest flights across multiple destinations and dates.

Request

Body parameters:

origin

string

required

3-letter IATA airport code

destination

string

Specific 3-letter IATA code (optional). If omitted, searches popular destinations.

date_from

string

Start date in YYYY-MM-DD format

date_to

string

End date in YYYY-MM-DD format

num_days

number

default:"7"

Number of days to search (1-14)

adults

number

default:"1"

Number of passengers (1-10)

Response

boolean

required

Request success status

origin

string

Origin airport code

rows

array

Array of flight options

Show Row object

date

string

Departure date

destination

string

Destination IATA code

destinationName

string

Destination airport/city name

offer

object

FlightOffer object (same structure as search endpoint)

overallCheapest

object | null

Cheapest flight offer across all results

Example request

curl -X POST http://localhost:8080/api/flights/serp/explore \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "JFK",
    "num_days": 7,
    "adults": 1
  }'

Example response

{
  "ok": true,
  "origin": "JFK",
  "rows": [
    {
      "date": "2026-03-03",
      "destination": "LAX",
      "destinationName": "Los Angeles International Airport",
      "offer": {
        "id": "serp-exp-0-token",
        "totalAmount": "198",
        "totalCurrency": "USD",
        "owner": { "name": "United", "iataCode": "" },
        "bookUrl": "https://www.google.com/travel/flights?...",
        "slices": []
      }
    }
  ],
  "overallCheapest": {
    "id": "serp-exp-0-token",
    "totalAmount": "198",
    "totalCurrency": "USD"
  }
}

Get return flights

POST /api/flights/serp/return-flights

Fetch return flight options after selecting outbound flight.

Request

Body parameters:

departure_token

string

required

Departure token from selected outbound flight

outbound_date

string

required

Outbound departure date (YYYY-MM-DD)

return_date

string

required

Return departure date (YYYY-MM-DD)

arrival_id

string

required

3-letter IATA code of trip origin (return destination)

departure_id

string

required

3-letter IATA code of trip destination (return origin)

adults

number

default:"1"

Number of passengers (1-10)

outbound_offer_id

string

Optional outbound offer ID for reference

Response

boolean

required

Request success status

offers

array

Array of return flight offers (FlightOffer structure)

Example request

curl -X POST http://localhost:8080/api/flights/serp/return-flights \
  -H "Content-Type: application/json" \
  -d '{
    "departure_token": "WyJbWyJKRktcIixcIjIwMjYtMDQtMTVcIl1d",
    "outbound_date": "2026-04-15",
    "return_date": "2026-04-22",
    "arrival_id": "JFK",
    "departure_id": "LAX",
    "adults": 2
  }'

Example response

{
  "ok": true,
  "offers": [
    {
      "id": "serp-return-outbound-0-token",
      "totalAmount": "289",
      "totalCurrency": "USD",
      "owner": { "name": "American", "iataCode": "" },
      "departureToken": "token-value",
      "slices": []
    }
  ]
}

Check flight status

POST /api/flights/status

Get real-time flight status using AeroAPI and Aviationstack.

Request

Body parameters:

flight_number

string

required

Flight number (e.g., “AA123”, “DL 456”)

departure_date

string

required

Departure date in YYYY-MM-DD format

Response

boolean

required

Request success status

flight

object

Flight status details

Show Flight object

flightNumber

string

Flight number

airline

string

Airline name

airlineLogoUrl

string

URL to airline logo image

routeFrom

string

Origin airport IATA code

routeTo

string

Destination airport IATA code

departureAirportName

string

Origin airport name

arrivalAirportName

string

Destination airport name

departureLocal

string

Local departure time

arrivalLocal

string

Local arrival time

departureTimezone

string

Departure timezone

arrivalTimezone

string

Arrival timezone

duration

string

Flight duration (e.g., “5h 30m”)

terminalGate

string

Terminal and gate information

stops

number

Number of stops

Example request

curl -X POST http://localhost:8080/api/flights/status \
  -H "Content-Type: application/json" \
  -d '{
    "flight_number": "AA123",
    "departure_date": "2026-03-15"
  }'

Example response

{
  "ok": true,
  "flight": {
    "flightNumber": "AA123",
    "airline": "American Airlines",
    "airlineLogoUrl": "https://www.gstatic.com/flights/airline_logos/70px/AA.png",
    "routeFrom": "JFK",
    "routeTo": "LAX",
    "departureAirportName": "John F. Kennedy International Airport",
    "arrivalAirportName": "Los Angeles International Airport",
    "departureLocal": "8:00 AM",
    "arrivalLocal": "11:30 AM",
    "departureTimezone": "America/New_York",
    "arrivalTimezone": "America/Los_Angeles",
    "duration": "6h 30m",
    "terminalGate": "Dep T8 G12 · Arr T4 G42",
    "stops": 0
  }
}

Error responses

Status codes:

400 - Invalid flight number or date format
404 - Flight not found
503 - Flight status API not configured
500 - Internal server error

Overview

Frontend APIs

Backend APIs

Flight API endpoints

Search flights

POST /api/flights/serp/search

Request

Response

Example request

Example response

Error responses

Get booking options

POST /api/flights/serp/booking-options

Request

Response

Example request

Example response

Error responses

Explore destinations

POST /api/flights/serp/explore

Request

Response

Example request

Example response

Get return flights

POST /api/flights/serp/return-flights

Request

Response

Example request

Example response

Check flight status

POST /api/flights/status

Request

Response

Example request

Example response

Error responses

Build docs developers (and LLMs) love

Overview

Frontend APIs

Backend APIs

​Search flights

POST /api/flights/serp/search

​Request

​Response

​Example request

​Example response

​Error responses

​Get booking options

POST /api/flights/serp/booking-options

​Request

​Response

​Example request

​Example response

​Error responses

​Explore destinations

POST /api/flights/serp/explore

​Request

​Response

​Example request

​Example response

​Get return flights

POST /api/flights/serp/return-flights

​Request

​Response

​Example request

​Example response

​Check flight status

POST /api/flights/status

​Request

​Response

​Example request

​Example response

​Error responses

Build docs developers (and LLMs) love

Search flights

Request

Response

Example request

Example response

Error responses

Get booking options

Request

Response

Example request

Example response

Error responses

Explore destinations

Request

Response

Example request

Example response

Get return flights

Request

Response

Example request

Example response

Check flight status

Request

Response

Example request

Example response

Error responses