avia-api

Async Python client for the Aviasales / Travelpayouts Data API - historical/cached ticket prices, price calendars, and reference data (countries, cities, airports, airlines, routes).

Not covered: real-time search (Aviasales Flights Search API) and the GraphQL API - these are separate products with a different interaction model.

Installation

The package is available through any standard package manager:

pip install avia-api
# or
uv add avia-api
# or
poetry add avia-api

Requires Python 3.11+.

Quick start

import asyncio
from avia_api import AviaApiClient

async def main() -> None:
    async with AviaApiClient(token="YOUR_TOKEN") as client:
        prices = await client.prices.cheap(origin="MOW", destination="LED")
        for destination, by_index in prices.items():
            for entry in by_index.values():
                print(destination, entry.price, entry.airline, entry.departure_at)

asyncio.run(main())

You can also skip passing the token explicitly and put it in the TRAVELPAYOUTS_TOKEN environment variable - the client will pick it up automatically. Get a token in your personal dashboard: https://www.travelpayouts.com/programs/100/tools/api

Resources and endpoints

All methods return models validated by pydantic

client.prices - prices

client.directions - popular routes

client.reference - reference data

Public, rarely changing JSON files:

Client configuration

from avia_api import AviaApiClient
from pyrate_limiter import Rate, Duration

client = AviaApiClient(
    token="...",
    rate=Rate(5, Duration.SECOND),   # outgoing request rate limit (pyrate-limiter)
    max_retries=3,                   # retries on 429/5xx and connection drops
    cache_ttl=1800,                  # seconds; None disables the response cache
    cache_path="avia_api.db",        # sqlite cache file (hishel), relative path
                                      # goes under .cache/hishel/
    timeout=10.0,
)

• Rate limiting - pyrate-limiter, a single bucket per client. Limits the rate of outgoing requests before they're sent, to avoid getting a 429 from the API.
• Retries - tenacity with exponential backoff and jitter; on 429 the Retry-After header is honored if present, but capped at 60 seconds per attempt - an unusually large value from the server (e.g. during an incident on its side) can't stall a request indefinitely.
• Cache - hishel on top of sqlite. Travelpayouts responses don't send Cache-Control, so FilterPolicy is used (any successful GET is cached, with entry lifetime governed by cache_ttl) instead of RFC 9111.

For tests or non-standard scenarios you can pass transport=... - your own httpx.AsyncBaseTransport, which fully disables rate limiting/retry/cache, and requests go straight through it (see respx or httpx.MockTransport).

Error handling

All exceptions derive from avia_api.AviaApiError:

Logging

The library uses standard logging. To see logs, enable the desired level for the avia_api logger:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("avia_api").setLevel(logging.DEBUG)

What is logged and at what level: