API documentation
The whole database as JSON: correlations, covariance, beta, volatility and holdings overlap for every tracked pair and asset. Free with attribution. No key, no signup, CORS open, refreshed daily after the US close.
Quickstart
curl https://www.pairbook.io/api/v1/pairs/aapl-vs-msft.json
const r = await fetch("https://www.pairbook.io/api/v1/pairs/aapl-vs-msft.json"); const pair = await r.json(); console.log(pair.correlation_weekly["3y"]);
import requests pair = requests.get("https://www.pairbook.io/api/v1/pairs/aapl-vs-msft.json").json() print(pair["correlation_weekly"]["3y"])
Endpoints
| Endpoint | Returns |
|---|---|
| GET /api/v1/index.json | Universe: every symbol with name, kind, canonical slug and URLs |
| GET /api/v1/symbols/{slug}.json | One asset: beta, volatility, returns, most correlated partners, diversifiers |
| GET /api/v1/pairs/{a}-vs-{b}.json | One pair (slugs in alphabetical order): correlations 1/3/5y, covariance, betas, volatilities, overlap |
| GET /api/v1/series/{slug}.json | Weekly return series (up to 156 weeks), so you can compute any pair yourself |
| GET /api/v1/badge/{a}-vs-{b}.svg | Embeddable SVG badge with the pair's 3-year correlation |
| GET /api/openapi.json | OpenAPI 3.1 specification of this API |
Pair slugs are lowercase symbols in alphabetical order, dots replaced by dashes (BRK.B becomes brk-b). When in doubt, /api/v1/index.json lists the canonical slug of every symbol.
Badges
Every pair ships with an SVG badge that updates with the data. Drop it in a README, a notebook or an internal dashboard:
[](https://www.pairbook.io/pair/spy-vs-tlt/)
Green means the pair diversifies (correlation at or below 0.20), blue means it moves as one (0.70 or above), gray sits in between.
Fields
Correlations are Pearson coefficients on weekly returns over windows of 52, 156 and 260 weeks. Covariance is annualized and expressed in %². Overlap is the sum of minimum common weights between two funds, in percent, with the issuer file date attached. Full definitions and formulas live on the methodology page.
Caching & freshness
Responses are static files behind a CDN and carry a one-hour cache header; the dataset itself changes once per trading day, after the US close. The as_of field in every response tells you exactly which trading day you are looking at. Please cache on your side accordingly.
Terms
The core API is free and will remain free. Attribution required: link back to this site wherever the data is displayed (the badge does this for you). Keep request volumes reasonable, and prefer the CSV download over crawling the endpoints when you want the dataset in bulk. The published figures are licensed CC BY 4.0, so redistribution is allowed with credit. No warranty of any kind, and nothing served by this API is investment advice.
