aperiodic 3.1.0

Client library for Aperiodic aggregate market data API - OHLCV and more

Aperiodic Data Client

Python client library for the Aperiodic aggregate market data API. Access pre-computed OHLCV candlestick data and other market aggregates with parallel downloads for optimal performance.

Installation

pip install aperiodic

Or install from source:

git clone https://github.com/aperiodic-io/aperiodic-client.git
cd aperiodic-io
pip install -e .

Symbology

All symbol identifiers follow the Atlas unified symbology — a standardised, exchange-agnostic naming scheme. Use Atlas to look up or convert symbol names before passing them to any function in this client.

Refer to the Atlas repository for the full symbol catalogue and conversion utilities.

Quick Start

from datetime import date
from aperiodic import get_metric

# Fetch hourly OHLCV data for BTC
df = get_metric(
    api_key="your-api-key",
    timestamp="true",
    interval="1h",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 3, 31),
)

print(df.head())

Features

• Parallel Downloads: Files are downloaded concurrently for fast data retrieval
• Per-File Retry: Each file download has independent retry with exponential backoff
• Date Range Support: Fetch data spanning multiple months in a single call
• Progress Bar: Visual progress indication with tqdm
• Type Hints: Full type annotations for IDE support
• Async Support: Both sync and async APIs available
• Jupyter Compatible: Works seamlessly in Jupyter notebooks

API Reference

get_metric

Fetch historical OHLCV (Open, High, Low, Close, Volume) data.

def get_metric(
    api_key: str,
    timestamp: Literal["exchange", "true"],
    interval: Literal["1m", "5m", "15m", "30m", "1h", "4h", "1d"],
    exchange: Literal["binance-futures", "binance"],
    symbol: str,
    start_date: date,
    end_date: date,
    show_progress: bool = True,
    max_concurrent: int = 10,
) -> pl.DataFrame

Parameters:

Parameter	Type	Description
api_key	str	Your Aperiodic API key
timestamp	"exchange" | "true"	Timestamp source - "exchange" for exchange-reported time, "true" for actual arrival time
interval	str	Aggregation interval ("1m", "5m", "15m", "30m", "1h", "4h", "1d")
exchange	str	Source exchange ("binance-futures", "binance")
symbol	str	Trading pair symbol in Atlas unified symbology (e.g., "perpetual-BTC-USDT:USDT")
start_date	date	Start date for the data range
end_date	date	End date for the data range (inclusive)
base_url	str	API base URL (optional)
show_progress	bool	Show download progress bar (default: True)
max_concurrent	int	Maximum concurrent downloads (default: 10)

Returns:

pl.DataFrame with columns:

• timestamp: Unix timestamp in milliseconds
• datetime: Parsed datetime (added by client)
• open: Opening price
• high: Highest price
• low: Lowest price
• close: Closing price
• volume: Trading volume

get_metric_async

Async version of get_metric. Use this when you're already in an async context.

import asyncio
from aperiodic import get_metric_async

async def main():
    df = await get_metric_async(
        api_key="your-api-key",
        timestamp="true",
        interval="1h",
        exchange="binance-futures",
        symbol="btcusdt",
        start_date=date(2024, 1, 1),
        end_date=date(2024, 3, 31),
    )
    return df

df = asyncio.run(main())

get_symbols

Get the list of available symbols for an exchange.

from aperiodic import get_symbols

symbols = get_symbols(
    api_key="your-api-key",
    exchange="binance-futures",
)

print(f"Found {len(symbols)} symbols")
print(symbols[:10])  # First 10 symbols

Parameters:

Parameter	Type	Description
api_key	str	Your Aperiodic API key
exchange	str	Source exchange ("binance-futures", "binance")
bucket	str	Data bucket (default: "ohlcv")
base_url	str	API base URL (optional)

Returns:

list[str] - List of available symbol names (lowercase)

Error Handling

from aperiodic import get_metric, APIError, DownloadError

try:
    df = get_metric(...)
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.details:
        print(f"Details: {e.details}")
except DownloadError as e:
    print(f"Failed to download {e.year}-{e.month:02d}: {e.original_error}")

Data Storage

Data is stored using Hive partitioning in Parquet format:

{timestamp}/{interval}/exchange={exchange}/symbol={symbol}/year={year}/month={month}.parquet

The client handles all the complexity of fetching multiple monthly files and combining them into a single DataFrame.

Package Structure

The client is organized into modules for different data types:

aperiodic/
├── ohlcv/              # OHLCV candlestick data
│   └── historical.py   # Historical data retrieval
├── general/            # General utilities
│   └── symbols.py      # Symbol listing
├── client.py           # Shared utilities and base functionality
├── config.py           # Configuration constants
└── types.py            # Type definitions

You can import directly from the package or from submodules:

# Direct import (recommended)
from aperiodic import get_metric, get_symbols

# Or import from submodules
from aperiodic.ohlcv import get_metric
from aperiodic.general import get_symbols

Requirements

• Python 3.11+
• httpx
• polars
• tqdm
• nest_asyncio (for Jupyter support)

License

MIT License - see LICENSE file for details.