# Cheap Flight Prices API: Airfare Calendar, Aviasales Data (`nabeelbaghoor/cheap-flight-prices-api`) Actor

Cheap flight prices and airfare trends from the Aviasales Data API: cheapest tickets for dates, month and week price calendars, non-stop fares, special offers, popular routes and destinations, plus IATA airport, city and airline data. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/cheap-flight-prices-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Travel, Developer tools, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 cached flight prices

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Cheap Flight Prices API: Airfare Calendar, Aviasales Data

Get cheap flight prices, airfare calendars and popular routes from the Aviasales Data API with your own Travelpayouts token, as clean rows you can export to CSV, Excel or JSON.

The Aviasales Data API, part of the Travelpayouts travel affiliate network, serves flight prices that Aviasales users found in their recent searches, cached for up to 7 days. This actor wraps its documented read routes: cheapest tickets for dates, grouped prices, latest prices, month and week price calendars, nearby alternative airports, price range search, special offers, popular departure cities, 0 to 2 stop and non-stop fares, daily price trends and popular destinations, plus the public IATA reference files of countries, cities, airports and airlines. Use it for flight deal sites, travel blogs and static route pages, fare alerts, airfare trend analysis, price monitoring and travel market research. Bring your own API key.

BYOK, not live tested: every route, parameter and response field comes from the Travelpayouts help centre article "Aviasales Data API" and the developer reference, and every price route was probed on 2026-10-30 with an invalid token. The actor has not been run against a live token.

### What it does

- **Cheapest tickets for dates** (v3 prices_for_dates): the cheapest fares found in the last 48 hours for a route and a departure and return month or day, one way or round trip, non-stop or with stops, sorted by price or route popularity. Up to 1,000 rows a page.
- **Grouped prices** (v3 grouped_prices): the cheapest ticket for each departure day or each month, with trip length limits.
- **Latest prices** (v3 get_latest_prices): prices found for a year, month or day, grouped by dates or destinations, by cabin class and length of stay, for one route or every route.
- **Month and week price calendars** (v2 month-matrix, week-matrix): a price for each day of a month, or for the 7 days around your departure and return dates.
- **Nearby alternative airports** (v2 nearest-places-matrix): prices between the cities closest to your origin and destination.
- **Price range search** (v3 search_by_price_range): tickets between a minimum and maximum price.
- **Special offers** (v3 get_special_offers): abnormally low fares on a route, optionally for one airline.
- **Popular directions** (v3 get_popular_directions): the cheapest tickets to a destination from the departure cities that search it most.
- **Cheapest and non-stop tickets, price trends, popular destinations** (v1 prices/cheap, prices/direct, prices/calendar, city-directions).
- **IATA reference data**: countries, cities with coordinates and time zones, airports and airlines, in ten languages, filtered by code, country or flightable status. No token needed.
- **Ready ticket links**: each ticket row carries the API's relative link and a full aviasales.com `ticketUrl`, with your affiliate marker added when you set one.
- **Pay only for results**: empty answers and refused lookups become a free row that says why.

### How to get your own token

1. Join the free Travelpayouts affiliate network at travelpayouts.com.
2. Open your profile and copy the token from the API token section (app.travelpayouts.com/profile/api-token).
3. Paste it into the Travelpayouts API token field of this actor, or set the DATA_API_KEY environment secret. It is sent only in the X-Access-Token header.

### Input

| Field | Modes | Notes |
| --- | --- | --- |
| `mode` | all | one of the 17 modes below |
| `origins`, `destinations` | price modes | IATA city or airport codes; every origin pairs with every destination, up to 100 routes |
| `departureDate`, `returnDate` | date based modes | YYYY-MM or YYYY-MM-DD (v1 routes take months) |
| `oneWay`, `direct`, `sorting`, `uniqueRoutes` | tickets for dates, price range, latest prices | API filters |
| `groupBy`, `periodType`, `tripClass`, `tripDuration`, `minTripDuration`, `maxTripDuration` | grouped and latest prices, month calendar | |
| `showToAffiliates` | latest prices and the v2 matrices | partner marker prices only (API default) or all prices |
| `nearbyVariants`, `flexibility` | nearby airports | 1 to 20 variants, 0 to 7 days |
| `calendarType`, `stayLength` | price trends | departure or return day, length of stay |
| `minPrice`, `maxPrice` | price range | required for that mode |
| `airline` | special offers | IATA airline code |
| `currency`, `market`, `locale` | price modes | default currency usd |
| `marker` | ticket modes | your affiliate marker, added to `ticketUrl` |
| `dataLanguage`, `iataCodes`, `countryCodes`, `flightableOnly` | reference modes | filters applied before charging |
| `maxResults` | all | most rows returned and charged, default 100 |
| `requestsPerMinute` | all | pacing, default 60 |
| `apiKey` | price modes | your Travelpayouts token, stored as a secret |

| Mode | Route |
| --- | --- |
| `pricesForDates` | GET /aviasales/v3/prices_for_dates |
| `groupedPrices` | GET /aviasales/v3/grouped_prices |
| `latestPrices` | GET /aviasales/v3/get_latest_prices |
| `monthMatrix` | GET /v2/prices/month-matrix |
| `weekMatrix` | GET /v2/prices/week-matrix |
| `nearestPlaces` | GET /v2/prices/nearest-places-matrix |
| `priceRange` | GET /aviasales/v3/search_by_price_range |
| `specialOffers` | GET /aviasales/v3/get_special_offers |
| `popularDirections` | GET /aviasales/v3/get_popular_directions |
| `cheapPrices` | GET /v1/prices/cheap |
| `directPrices` | GET /v1/prices/direct |
| `calendarPrices` | GET /v1/prices/calendar |
| `cityDirections` | GET /v1/city-directions |
| `countries`, `cities`, `airports`, `airlines` | GET /data/{language}/{file}.json |

Example input:

```json
{
    "mode": "pricesForDates",
    "origins": ["MAD"],
    "destinations": ["BCN"],
    "departureDate": "2026-12",
    "returnDate": "2027-01",
    "oneWay": "false",
    "currency": "usd",
    "marker": "123456"
}
```

### Output

One row per price or record. Illustrative row (values from the documented response example, trimmed; not a live response):

```json
{
    "mode": "pricesForDates",
    "recordType": "flightPrice",
    "query": "MAD-BCN",
    "found": true,
    "origin": "MAD",
    "destination": "BCN",
    "originAirport": "MAD",
    "destinationAirport": "BCN",
    "departureAt": "2023-07-28T07:00:00+02:00",
    "returnAt": "2023-08-26T14:30:00+02:00",
    "price": 5929,
    "currency": "usd",
    "airline": "IB",
    "flightNumber": "3002",
    "transfers": 0,
    "returnTransfers": 0,
    "durationMinutes": 165,
    "durationToMinutes": 80,
    "durationBackMinutes": 85,
    "link": "/search/MAD2807BCN26081?t=IB1690520400...&expected_price_currency=usd",
    "ticketUrl": "https://www.aviasales.com/search/MAD2807BCN26081?t=IB1690520400...&expected_price_currency=usd&marker=123456",
    "record": { "...": "the full API record" }
}
```

Calendar and matrix rows add `foundAt`, `distanceKm`, `tripClass`, `actual` and `groupKey` (the day or month of a grouped price, or the offer's place in a v1 result). Special offers add `originName`, `destinationName` and `airlineName`. Reference rows fill `code`, `name`, `countryCode`, `cityCode`, `timeZone`, `latitude`, `longitude` and `flightable`.

### Pricing

Pay per event, only for rows that carry a real record:

| Event | Price |
| --- | --- |
| Cached flight price (ticket, calendar day, offer, destination or departure city) | $0.008 |
| Country, city, airport or airline record | $0.005 |

The Aviasales Data API itself is free for Travelpayouts partners, within its per minute rate limits.

### FAQ

#### What is the Aviasales Data API?

It is the free flight price API of Travelpayouts, the travel affiliate network of the Aviasales group. It returns prices that Aviasales users found in recent searches, cached for up to 7 days, so it suits static pages, price calendars and deal lists rather than live booking.

#### Do I need my own Travelpayouts token?

Yes, for every price mode. This actor is bring your own key: it calls the API with your token and under your Travelpayouts account. Without a token a price mode ends straight away with a message saying how to get one, and nothing is charged. The countries, cities, airports and airlines modes are public files and need no token.

#### Are these live flight prices?

No. They are cached prices from real Aviasales searches, usually from the last 48 hours for the v3 routes. Check `expiresAt` or `foundAt`, and confirm the fare on Aviasales through `ticketUrl` before relying on it. The real time Flight Search API needs a separate approval from Travelpayouts and is not wrapped.

#### Why did a route return no prices?

The cache only holds routes and dates people actually searched, per market. Try a different month, leave the return date empty, set the market that matches your audience (us, gb, de), or widen the route to a city code such as LON instead of an airport code.

#### How does the affiliate marker work?

Set your Travelpayouts marker and every ticket row gets a `ticketUrl` on aviasales.com with marker= added, while the raw `link` stays as the API returned it. For tracked short links, paste the ticket URL into the link generator in your Travelpayouts account.

#### Which currencies and markets are supported?

Any currency code the API accepts, such as usd, eur, gbp or rub (the API default), and any Aviasales market code. The market decides which site's cache is read; by default it follows the origin.

#### How many requests does a run make?

One per route for most modes, plus one per page for the paged modes. The default pacing of 60 a minute stays under every documented route limit, and the Travelpayouts affiliate terms ask partners to keep load modest and cache results, which a scheduled run with a dataset does.

#### Where do IATA codes come from?

From the countries, cities, airports and airlines modes of this actor, which read the same public files the API documentation links to.

### Keyword map

cheap flight prices API, airfare API, flight price calendar, Aviasales API, Travelpayouts API, flight data API, cheapest flights by month, flight price trends, low fare calendar, non-stop flights API, flight deals API, special offers airfare, popular flight routes, IATA airport codes, airline codes database, travel affiliate API, flight price monitoring.

### Routes and verification

Every price route was probed twice on 2026-10-30 with a realistic length invalid token: prices_for_dates, month-matrix, prices/cheap, city-directions and get_popular_directions answered 401 `Unauthorized`, while the invented routes /aviasales/v3/flight_prices_list and /v9/prices/cheapest answered 404 `404 page not found`. The actor ends cleanly on a 401 or 403, reads a 404 page not found as a bug, and reads a 200 with success false as a refusal of that one route. The /data reference files answered 200 without a token. The deprecated v1 airline-directions, v1 prices/monthly and v2 prices/latest routes and the real time Flight Search API are not wrapped. The calendar route's date parameter is sent as depart_date, as in both documented request examples (one parameter list spells it departure_date).

### Licensing and data use

This actor works only with your own Travelpayouts token, and the Travelpayouts Affiliate Agreement applies to how you use the data. The agreement allows integrating the API tools into your projects, recommends caching results for about 24 hours, and forbids parasitic load. Keep your marker on links you publish. This actor is not affiliated with or endorsed by Travelpayouts or Aviasales.

# Actor input Schema

## `mode` (type: `string`):

Each mode calls one documented Aviasales Data API route. The price modes need your Travelpayouts API token; the four reference file modes do not. Prices come from a cache of what Aviasales users searched recently, not from a live search.

## `origins` (type: `array`):

IATA city or airport codes to fly from, such as LON, NYC or MAD, one per line. Every origin is paired with every destination, up to 100 routes a run. Popular destinations from a city reads origins only.

## `destinations` (type: `array`):

IATA city or airport codes to fly to, such as BCN, PAR or HKT, one per line. Optional in several modes (leave it empty for every destination); required for the month, week and day price calendars, nearby airports and grouped prices. Popular directions reads destinations only.

## `departureDate` (type: `string`):

Optional. YYYY-MM or YYYY-MM-DD, such as 2026-12 or 2026-12-18. The v1 routes and the nearby airports matrix take a month only. Latest prices also take a year (YYYY) with the period type below.

## `returnDate` (type: `string`):

Optional. YYYY-MM or YYYY-MM-DD. Leave empty for one way tickets.

## `oneWay` (type: `string`):

Tickets for dates, latest prices, month calendar and price range. The API default is one way.

## `direct` (type: `string`):

Tickets for dates, grouped prices and price range. The API default includes tickets with stops.

## `sorting` (type: `string`):

Tickets for dates take price or route popularity; latest prices also take price per kilometre.

## `uniqueRoutes` (type: `boolean`):

Tickets for dates with only an origin set: return one ticket per route (sent as unique=true).

## `groupBy` (type: `string`):

Grouped prices group by departure day or by month; latest prices group by dates or by destinations.

## `periodType` (type: `string`):

Latest prices: the period the departure date names. Without it the API returns flights in the current month.

## `tripClass` (type: `string`):

Latest prices only.

## `tripDuration` (type: `integer`):

Optional. Latest prices: length of stay in days. Month calendar: length of stay in weeks (1 to 52).

## `minTripDuration` (type: `integer`):

Optional. Grouped prices: shortest stay between departure and return.

## `maxTripDuration` (type: `integer`):

Optional. Grouped prices: longest stay between departure and return.

## `showToAffiliates` (type: `string`):

Latest prices and the month, week and nearby matrices. The API default (true) returns only prices found through partner markers, which the docs recommend.

## `nearbyVariants` (type: `integer`):

Optional. Nearby airports: how many origin and destination variants to return, 1 to 20 (1 is just the route asked for).

## `flexibility` (type: `integer`):

Optional. Nearby airports: widen the dates by up to 7 days either side.

## `calendarType` (type: `string`):

Flight price trends: one row per departure day or per return day.

## `stayLength` (type: `integer`):

Optional. Flight price trends: length of stay in the destination.

## `minPrice` (type: `integer`):

Price range search: the lowest ticket price, in the chosen currency.

## `maxPrice` (type: `integer`):

Price range search: the highest ticket price, in the chosen currency.

## `airline` (type: `string`):

Optional. Special offers: only offers from this airline, such as BA or IB.

## `currency` (type: `string`):

Three letter currency code for prices, such as usd, eur or gbp. The API default is rub.

## `market` (type: `string`):

Optional. Two letter data source market, such as us, gb or de. Each Aviasales site keeps its own cache; by default the market follows the origin.

## `locale` (type: `string`):

Optional. Popular directions, special offers and price range: language of city and airline names, such as en or de.

## `marker` (type: `string`):

Optional. Your Travelpayouts partner marker. It is added as marker= to every ticketUrl built from the API's ticket links; the raw link is kept unchanged in the link column.

## `dataLanguage` (type: `string`):

Countries, cities, airports and airlines modes: the language of the file.

## `iataCodes` (type: `array`):

Optional. Reference modes: keep only these codes, such as LHR, LON or BA. Filtered in the actor, so only matching rows are charged.

## `countryCodes` (type: `array`):

Optional. Countries, cities and airports modes: keep only these two letter country codes.

## `flightableOnly` (type: `boolean`):

Cities and airports modes: keep only cities with a flightable airport and airports marked flightable.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for, across all routes.

## `requestsPerMinute` (type: `integer`):

Pacing for calls to the API. The documented limits are 60 to 600 a minute per route; the default keeps load modest, as the affiliate terms ask.

## `apiKey` (type: `string`):

Your Aviasales Data API token from the API token section of your Travelpayouts profile. Needed for every price mode, not for the reference files. Stored as a secret, sent only in the X-Access-Token header to api.travelpayouts.com and never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "pricesForDates",
  "origins": [
    "MAD"
  ],
  "destinations": [
    "BCN"
  ],
  "oneWay": "",
  "direct": "",
  "sorting": "",
  "groupBy": "",
  "periodType": "",
  "tripClass": "",
  "showToAffiliates": "",
  "calendarType": "",
  "currency": "usd",
  "dataLanguage": "en",
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per ticket price, calendar day, offer, departure city, destination, country, city, airport or airline the chosen mode read.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "origins": [
        "MAD"
    ],
    "destinations": [
        "BCN"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/cheap-flight-prices-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "origins": ["MAD"],
    "destinations": ["BCN"],
}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/cheap-flight-prices-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "origins": [
    "MAD"
  ],
  "destinations": [
    "BCN"
  ]
}' |
apify call nabeelbaghoor/cheap-flight-prices-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/cheap-flight-prices-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/odRCteely8VcomrXD/builds/Wz41zkc8thwmRpiRy/openapi.json