Flight search

A flight search takes your route and passengers and returns priced offers. Each offer is a complete, bookable itinerary with a fixed price. You pick one, revalidate it, and turn it into an order.

Find origins & destinations

GET/v3/HAPI/flights/places

Autocomplete for the search form: resolve a typed city/airport name (or an IATA code) into flightable places. Requires the flights:read scope.

GET https://api.hermeseus.com/v3/HAPI/flights/places?query=istan&limit=5

{
  "object": "flight_place_list",
  "data": [
    { "object": "flight_place", "code": "IST", "name": "Istanbul", "type": "city",
      "city_code": "IST", "country_code": "TR", "country": "Türkiye" },
    { "object": "flight_place", "code": "IST", "name": "Istanbul Airport", "type": "airport",
      "city_code": "IST", "country_code": "TR", "country": "Türkiye" }
  ]
}

Use the returned code as a slice's origin / destination.

Create a search

POST/v3/HAPI/flights/searches

Requires the flights:read scope.

Body

Field	Type	Required	Description
`slices`	array	Yes	One entry per leg. One slice is one-way; two is a round trip; more is multi-city.
`slices[].origin`	string	Yes	Origin IATA code, e.g. `IST`.
`slices[].destination`	string	Yes	Destination IATA code, e.g. `DXB`.
`slices[].departure_date`	string	Yes	Departure day, `YYYY-MM-DD`.
`passengers.adults`	integer	Yes	Number of adults (at least 1).
`passengers.children`	integer	No	Number of children.
`passengers.infants`	integer	No	Number of infants.
`cabin_class`	string	No	One of `economy`, `premium_economy`, `business`, `first`.
`max_offers`	integer	No	Cap on offers returned.

curl -X POST https://api.hermeseus.com/v3/HAPI/flights/searches \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slices": [
      { "origin": "IST", "destination": "DXB", "departure_date": "2026-11-14" }
    ],
    "passengers": { "adults": 1 },
    "cabin_class": "economy"
  }'

const res = await fetch("https://api.hermeseus.com/v3/HAPI/flights/searches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    slices: [
      { origin: "IST", destination: "DXB", departure_date: "2026-11-14" }
    ],
    passengers: { adults: 1 },
    cabin_class: "economy"
  })
});

const search = await res.json();

import requests

res = requests.post(
    "https://api.hermeseus.com/v3/HAPI/flights/searches",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "slices": [
            {"origin": "IST", "destination": "DXB", "departure_date": "2026-11-14"}
        ],
        "passengers": {"adults": 1},
        "cabin_class": "economy",
    },
)

search = res.json()

Response

A flight_search holding the offers. Money is always a { amount, currency } object in USD.

{
  "object": "flight_search",
  "id": "srch_1837",
  "status": "completed",
  "offer_count": 1,
  "offers": [
    {
      "object": "flight_offer",
      "id": "ofr_dHJhdmVscGF5b3V0czphYmMxMjNfcDA",
      "owner": "TP",
      "validating_airline": "PC",
      "airline_name": "Pegasus Airlines",
      "cabin_class": "economy",
      "total": { "amount": "412.00", "currency": "USD" },
      "base":  { "amount": "250.00", "currency": "USD" },
      "tax":   { "amount": "162.00", "currency": "USD" },
      "passengers": [
        { "type": "adult", "count": 1,
          "total": { "amount": "412.00", "currency": "USD" },
          "base":  { "amount": "250.00", "currency": "USD" } }
      ],
      "slices": [
        {
          "origin": "IST",
          "destination": "DXB",
          "duration_minutes": 185,
          "segments": [
            {
              "origin": "IST",
              "destination": "DXB",
              "departing_at": "2026-11-14T08:10:00",
              "arriving_at": "2026-11-14T11:15:00",
              "marketing_carrier": "PC",
              "operating_carrier": "PC",
              "flight_number": "695",
              "aircraft": "320",
              "aircraft_name": "Airbus A320",
              "booking_class": "Y",
              "cabin_class": "economy",
              "stops": 0,
              "seats_remaining": 9,
              "baggage": { "checked": "20 Kilogram(s)", "cabin": "8 Kilogram(s)" },
              "duration_minutes": 185
            }
          ]
        }
      ]
    }
  ]
}

Offers are quotes, not holds. An offer reflects live availability at search time. Prices and seats can change, so revalidate the offer right before booking. The next step, get an offer, does exactly that.

The offer id

An ofr_ id fully identifies a fare. Pass it to revalidate the offer and then to create an order. Treat it as opaque.

Was this page helpful?

Versioning

Stream results