Flight price calendar

Get the cheapest fare per day for a route, so you can show a "cheapest dates" view before a full search.

POST/Air/AirPriceCalendar

Access requires the permission air_low_fare_search

Send an origin, a destination, and a month or a date. You get one cheapest fare per day. This endpoint is indicative. Run a full search to get bookable fares.

Path parameters

None.

Query parameters

None.

Body parameters

Name	Type	Required	Default	Description
`Origin`	string	Yes	-	Departure IATA code. Three letters, for example `IST`.
`Destination`	string	Yes	-	Arrival IATA code. Three letters, for example `DXB`.
`DepartDate`	string	Yes	-	A month `YYYY-MM` or a day `YYYY-MM-DD`.
`TripType`	string	No	round trip	`oneway` for one way. Any other value is treated as a round trip.
`ReturnDate`	string	No	-	A month or a day. Required for a round trip.
`CalendarType`	string	No	`departure_date`	Anchor the calendar on `departure_date` or `return_date`.
`Currency`	string	No	`USD`	Three-letter currency code.

Request

curl -X POST https://api.hermeseus.com/api/Air/AirPriceCalendar \
  -H "Content-Type: application/json" \
  -d '{
    "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
    "Origin": "IST",
    "Destination": "DXB",
    "DepartDate": "2026-10",
    "TripType": "oneway",
    "Currency": "USD"
  }'

const res = await fetch("https://api.hermeseus.com/api/Air/AirPriceCalendar", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    SessionId: "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
    Origin: "IST",
    Destination: "DXB",
    DepartDate: "2026-10",
    TripType: "oneway",
    Currency: "USD"
  })
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.hermeseus.com/api/Air/AirPriceCalendar",
    json={
        "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
        "Origin": "IST",
        "Destination": "DXB",
        "DepartDate": "2026-10",
        "TripType": "oneway",
        "Currency": "USD",
    },
)

data = res.json()

Response

Field	Type	Description
`Success`	boolean	`true` on success.
`Origin` / `Destination`	string	The route you asked for.
`TripType`	string	`OneWay` or `RoundTrip`.
`CalendarType`	string	`departure_date` or `return_date`.
`Currency`	string	Currency of every price.
`DaysCount`	integer	Number of days returned.
`MinPrice` / `MaxPrice`	number	Cheapest and most expensive day.
`Cheapest`	object	The single cheapest day, same shape as a `Days` entry.
`Days`	array of object	One entry per day. See below.
`Error`	object	`null` on success.

Days[] object

Field	Type	Description
`Date`	string	The day, `YYYY-MM-DD`.
`Price`	number	Cheapest fare that day.
`Currency`	string	Currency of `Price`.
`Transfers`	integer	Number of stops on the cheapest option.
`Airline`	string	Airline code of the cheapest option.
`FlightNumber`	string	Flight number of the cheapest option.
`DepartureAt`	string	Departure timestamp.
`ReturnAt`	string	Return timestamp, for a round trip.
`ExpiresAt`	string	When the quote expires.
`Origin` / `Destination`	string	Route of the entry.

{
  "Success": true,
  "Origin": "IST",
  "Destination": "DXB",
  "TripType": "OneWay",
  "CalendarType": "departure_date",
  "Currency": "USD",
  "DaysCount": 2,
  "MinPrice": 198.00,
  "MaxPrice": 233.00,
  "Cheapest": {
    "Date": "2026-10-12",
    "Price": 198.00,
    "Currency": "USD",
    "Transfers": 0,
    "Airline": "TK",
    "FlightNumber": "764",
    "DepartureAt": "2026-10-12T08:25:00",
    "ReturnAt": null,
    "ExpiresAt": "2026-09-20T10:00:00",
    "Origin": "IST",
    "Destination": "DXB"
  },
  "Days": [
    {
      "Date": "2026-10-12",
      "Price": 198.00,
      "Currency": "USD",
      "Transfers": 0,
      "Airline": "TK",
      "FlightNumber": "764",
      "DepartureAt": "2026-10-12T08:25:00",
      "ReturnAt": null,
      "ExpiresAt": "2026-09-20T10:00:00",
      "Origin": "IST",
      "Destination": "DXB"
    },
    {
      "Date": "2026-10-13",
      "Price": 233.00,
      "Currency": "USD",
      "Transfers": 1,
      "Airline": "GF",
      "FlightNumber": "552",
      "DepartureAt": "2026-10-13T02:10:00",
      "ReturnAt": null,
      "ExpiresAt": "2026-09-20T10:00:00",
      "Origin": "IST",
      "Destination": "DXB"
    }
  ],
  "Error": null
}

Errors

Code	Meaning	Fix
`Err0106001`	A field is missing or invalid, for example a missing `ReturnDate` on a round trip.	Fix the field named in the message.
`Err0500003`	No calendar data for that route and dates.	Try a different month or route.