API Reference — HF Data Library

Getting started

Base URL: https://api.hfdatalibrary.com/v1

All requests require an API key passed as a header:

curl -H "X-API-Key: your-key-here" \
  https://api.hfdatalibrary.com/v1/symbols

API keys are free. Register here with your name, institution, and email.

Rate limit: 300 requests per minute per API key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

Endpoints

GET /symbols

List all available tickers with metadata.

{
  "count": 1391,
  "symbols": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "start_date": "2002-12-30",
      "end_date": "2026-04-04",
      "bars_raw": 2847391,
      "bars_clean": 2846982,
      "quintile": 5,
      "source": "pitrading+alpaca"
    },
    ...
  ]
}

GET /symbols/{ticker}

Metadata for a single ticker: date range, bar counts, quality scores, data source.

GET /bars/{ticker}

Query 1-minute OHLCV bars for a ticker.

Parameters

Param	Type	Default	Description
start	date	earliest	Start date (YYYY-MM-DD)
end	date	latest	End date (YYYY-MM-DD)
version	string	clean	Data version: `raw`, `clean`, or `filled`
format	string	json	Response format: `json`, `csv`, or `parquet`
limit	int	10000	Max rows per response (pagination)
offset	int	0	Row offset for pagination

GET /bars/AAPL?start=2024-01-02&end=2024-01-02&version=clean&format=json

{
  "ticker": "AAPL",
  "version": "clean",
  "count": 389,
  "bars": [
    {
      "datetime": "2024-01-02 09:30:00",
      "open": 187.15,
      "high": 187.28,
      "low": 186.92,
      "close": 187.01,
      "volume": 1284300
    },
    ...
  ]
}

GET /bars/{ticker}/daily

Daily OHLCV bars aggregated from intraday data. Same parameters as /bars/{ticker}.

GET /variables/{ticker}

All 27 computed academic variables, daily frequency.

Parameters

Param	Type	Default	Description
start	date	earliest	Start date
end	date	latest	End date
version	string	clean	Data version
variables	string	all	Comma-separated list: `rv_5min,bns_z,amihud`
format	string	json	`json`, `csv`, or `parquet`

GET /variables/AAPL?start=2024-01-02&end=2024-01-02&variables=rv_5min,bns_z,amihud

{
  "ticker": "AAPL",
  "version": "clean",
  "data": [
    {
      "date": "2024-01-02",
      "rv_5min": 0.000043,
      "bns_z": 1.872,
      "amihud": 2.31e-12
    }
  ]
}

GET /quality/{ticker}

Daily data quality report: gap rate, observed bars, longest gap, bars since last trade.

GET /download/{ticker}

Download full history for a ticker as a single parquet file. Served directly from R2.

Parameters

Param	Type	Default	Description
version	string	clean	`raw`, `clean`, or `filled`

GET /bulk/{package}

Download pre-packaged bundles.

Package	Contents
sp500	All S&P 500 constituents
nasdaq100	All Nasdaq 100 constituents
all	Complete dataset (all 1,391 tickers)
sector-tech	Technology sector
sector-healthcare	Healthcare sector
sector-financials	Financials sector
quintile-1	Q1 (least liquid)
quintile-5	Q5 (most liquid)

Error codes

Code	Meaning
400	Bad request — invalid parameter (check date format, ticker name)
401	Unauthorized — missing or invalid API key
404	Not found — ticker doesn't exist in the dataset
429	Rate limit exceeded — wait and retry (see Retry-After header)
500	Server error — please report to aelkassabgi@uca.edu