API guide v1

One base URL, one header, tidy responses. Every endpoint returns the same envelope and honours your key's tier automatically. The machine-readable spec is openapi.yaml.

Basics

Envelope

{
  "as_of": "2026-09-18",            // date of the latest refresh behind this response
  "embargo_cutoff": "2026-04-09",   // trial keys: last date served (null on subscription)
  "tier": "trial",
  "dataset": "company_metrics",
  "schema_version": "2026-09",
  "rows": 1834,
  "next_cursor": null,
  "data": [ { "entity_id": "AAPL#consumer-electronics-dev", "company_id": "LF0000042", "perm_id": "4295905573", "ticker": "AAPL", "date": "2021-01-01", "metric": "mentions", "raw": 34297, "corrected": 34297, "flag": "" }, … ]
}

as_of is the knowledge date this response reflects (the kdate served, or the latest refresh when kdate is omitted).

Three calls to a first chart

export KEY=lf_live_xxxxxxxxxxxxxxxx

# 1. the universe (all entities, ownership windows, companyId/permID/ticker map)
curl -s -H "Authorization: Bearer $KEY" \
  "https://data.likefolio.com/v1/universe?format=csv" -o universe.csv

# 2. resolve a ticker to its stable companyId (key everything else by this)
curl -s -H "Authorization: Bearer $KEY" \
  "https://data.likefolio.com/v1/resolve?ticker=AAPL"        # -> companyId LF0000042

# 3. one company, every metric, corrected + raw + flag
curl -s -H "Authorization: Bearer $KEY" \
  "https://data.likefolio.com/v1/company/LF0000042/metrics?start=2021-01-01&format=csv" -o aapl.csv

import pandas as pd, requests
H = {"Authorization": f"Bearer {KEY}"}
u = "https://data.likefolio.com/v1/company/LF0000042/metrics"   # companyId, not ticker
df = pd.DataFrame(requests.get(u, headers=H, params={"metric": "mentions,pi"}).json()["data"])
wide = df.pivot_table(index="date", columns=["entity_id", "metric"], values="corrected").sort_index()
wide.rolling(28).mean().plot()

Endpoints

Point-in-time reads

Ownership is time-aware inside every series: at any date, an entity counts only the brands it owned that day, and a brand owned today is measured back to the epoch so year-over-year is like-for-like. You do not need to apply the windows yourself. For the trend map, pass as_of=YYYY-MM-DD to get membership as it stood.

Every metric, series and entity endpoint takes an optional kdate (knowledge date): it returns values as LikeFolio knew them on that Eastern day, with no look-ahead through later restatements (spike reclassifications, re-pulls, negations, methodology changes) or M&A. It is distinct from start/end, which bound the event date. An ISO date pins a single vintage; omit it for the latest. kdate=all returns the full bitemporal history, with kdate_from, kdate_to and change_reason on every row, for building walk-forward backtests through M&A and restatements. Because tickers are point-in-time too, keying by companyId keeps a backtest stable across a rename; resolve a ticker as-of a kdate via /resolve. Our data goes live in September 2026: there are no methodology changes or restatements before then, so kdate vintages run from go-live forward — use them to backtest through M&A and later corrections, not to claim a value was known before we built the series.

Corrections accrue forward. Every row that changes after first publication is logged with a knowledge date in /changelog; subscribers can request the append-only change file, or pull any historical vintage directly with kdate.

Errors