Dataset Characteristics

Flat Files Dataset Characteristics

Built for efficient historical data processing.

Historical market data becomes much more valuable when it's easy to discover, download, and process. Instead of requiring millions of API requests or complex pagination, CoinAPI Flat Files organize historical cryptocurrency market data into a predictable directory structure.

Every dataset follows the same standardized organization, making it easy to retrieve exactly the exchanges, symbols, dates, and data types your application needs. Files are available through an S3-compatible API and are stored as compressed CSV files for efficient transfer and processing.

Explore the Documentation Get Your API Key

Daily & Hourly Partitions

Large historical datasets shouldn't require downloading more data than necessary. CoinAPI organizes historical files into both daily and hourly UTC partitions, allowing developers to retrieve data at the granularity that best matches their workflow.

Daily files are ideal for long-term historical analysis, research, and backtesting, while hourly partitions make it easy to process recent market activity, build incremental ingestion pipelines, or replay specific trading sessions without downloading entire days of data. Both partition types coexist, giving developers complete flexibility.

Choosing a Partition

Partition	Typical Use Cases
Daily	Long-term historical analysis, backtesting, research, archive storage
Hourly	Incremental ingestion, intraday analytics, market replay, high-frequency workflows

Because all partitions use UTC timestamps, developers don't need to handle exchange-specific time zones or daylight saving adjustments when combining datasets from multiple trading venues.

Exchange-Level Dataset Organization

Historical data is organized by exchange, making it straightforward to retrieve data from a single trading venue or process multiple exchanges independently. Each exchange has its own directory within every dataset, allowing applications to filter downloads efficiently and build automated ingestion pipelines without scanning unnecessary files.

structure

T-TRADES/
└── D-20260101/
    ├── E-BINANCE/
    ├── E-COINBASE/
    ├── E-KRAKEN/
    └── E-BITSTAMP/

This organization also makes parallel downloads significantly easier. Multiple exchanges can be processed independently, improving throughput for research environments, distributed processing systems, and large-scale historical backfills.

Symbol-Level Historical Files

Within each exchange, historical data is stored as symbol-level files. Rather than combining thousands of instruments into a single dataset, CoinAPI creates dedicated files for individual trading pairs. File names include both the standardized CoinAPI Symbol ID and the original exchange symbol, together with internal identifiers used throughout the platform.

Whether you're analyzing BTC/USDT across multiple exchanges or building datasets for thousands of symbols, the file structure remains predictable and consistent.

This approach provides several advantages:

Download only the symbols your application requires.
Easily automate downloads for specific trading pairs.
Match historical datasets with CoinAPI metadata services.
Preserve both normalized and native exchange identifiers.
Simplify joins between historical files and other CoinAPI products.

A Standardized Directory Structure

Every Flat Files dataset follows the same logical organization, regardless of whether you're working with trades, quotes, full order books, or OHLCV data.

Compressed CSV Files

All Flat Files are delivered as gzip-compressed CSV files (.csv.gz), providing an excellent balance between portability, storage efficiency, and processing performance. Compressed files reduce storage requirements and transfer times while remaining compatible with virtually every modern analytics ecosystem.

After decompression, every dataset remains a standard CSV file, making it easy to inspect manually or integrate into existing workflows without proprietary formats or specialized software.

Process Flat Files directly using tools such as:

Python (Pandas, Polars)
Apache Spark
DuckDB
ClickHouse
PostgreSQL
Excel and spreadsheet applications
Custom ETL and data engineering pipelines

UTC Time Organization

Working with historical market data from multiple exchanges often means dealing with different time zones, inconsistent timestamps, and complex conversions. CoinAPI eliminates that complexity by organizing every Flat Files dataset using UTC-based time partitions. Daily and hourly directories, as well as timestamp fields inside the files, follow the same universal time standard.

For developers and quantitative researchers, this means:

No exchange-specific timezone conversions.
Consistent time alignment across all datasets.
Simpler joins between trades, quotes, order books, and OHLCV data.
Reliable historical replay and time-series analysis.

Datasets

Available Dataset Types

CoinAPI Flat Files cover the core datasets required for historical cryptocurrency market analysis. Each dataset follows the same directory structure and file organization while capturing a different aspect of market activity.

Dataset	What It Contains	Typical Use Cases
Trades	Every executed trade with timestamps, price, volume, identifiers, and aggressor side.	Trade replay, volume analysis, quantitative research, backtesting
Quotes	Best bid and ask prices with corresponding sizes.	Spread analysis, liquidity monitoring, market microstructure
Full Order Book	Every order book update required to reconstruct historical order books.	Order book replay, execution simulation, liquidity modeling
OHLCV	Aggregated candlestick data across multiple timeframes.	Charting, technical analysis, historical price research

Because every dataset shares a consistent structure, applications can switch between data types without redesigning ingestion pipelines or changing storage logic.

Optimized for Bulk Historical Downloads

Flat Files are designed for downloading and processing large amounts of historical data efficiently. Instead of querying individual API endpoints for every request, developers can retrieve complete historical datasets directly from S3-compatible storage and process them locally or in cloud-based analytics environments.

Combined with S3-compatible listing operations, applications can discover available files, estimate download sizes, and retrieve only the data required for a specific workflow.

Automate historical downloads by filtering on:

Dataset type
Exchange
Date partition
Symbol
File prefix

Predictable File Naming

Every Flat Files object follows a consistent naming convention that exposes key metadata directly in the file path.

This predictable naming scheme makes it easy to generate download paths programmatically, organize local storage, and automate large-scale ingestion workflows without maintaining custom mappings for each exchange.

Depending on the dataset, file names include:

Exchange identifier
CoinAPI Symbol ID
Native exchange symbol
Internal dataset identifier
Timeframe (for OHLCV datasets)

Dataset Characteristics

Historical Data Designed for Scale

Reliable historical data isn't just about accuracy — it's also about how easily it can be stored, discovered, and processed. CoinAPI Flat Files combine normalized cryptocurrency market data with a consistent, scalable dataset structure that supports everything from individual research projects to enterprise-scale data engineering pipelines.

Whether you're backtesting trading strategies, training AI models, replaying historical markets, or building quantitative research platforms, Flat Files provide a predictable foundation for working with cryptocurrency market history.