API docs v1 · contract 1.6.2
One base URL, one header, the same response shape everywhere. The API serves two families of data: X (social) company demand and consumer trends, and Google search interest for the brands behind each company. Your key's tier is applied automatically.
Basics
| Base URL | https://data.likefolio.com/v1 |
|---|---|
| Auth | Send your key on every request: Authorization: Bearer <YOUR_API_KEY>, or the raw key in X-API-Key. Downloads need the key too; there are no presigned links. Keep the key out of code and URLs. |
| Methods | Every data route is GET. The one exception is POST /v1/keys/rotate (below). |
| Formats | format=json (default) or csv, paged. format=parquet or arrow return the whole result as one file. See formats and paging. |
| Dates | start and end are inclusive YYYY-MM-DD America/New_York calendar days and bound the event date. |
| Missing values | Unavailable values are null, blank, or omitted according to the endpoint. Numeric values may include filled estimates; inspect search provenance and resolution. |
| Version | Path-versioned (/v1). This documents contract 1.6.2, the 2026-11-04 launch. See the changelog. |
| Spec | Machine-readable: openapi.yaml (Swagger 2.0 / OpenAPI 2.0, contract 1.6.2). |
Trial and subscription
Both tiers see the same data and the same columns, with these differences.
| Trial | Subscription | |
|---|---|---|
| How to get a key | Request one on the trial page. We confirm your email, approve the request, and the key arrives by email. The API itself has no signup endpoint. | Contact us. |
| Dates served | A rolling six-month embargo: no dated row or cross-section after embargo_cutoff (today minus six months). It is in every envelope. | Through the latest publication. |
| Search brands | Opaque brand ids (TICKER#bN), never brand names. | Brand names; /v1/search/brands also gives each brand's id. |
| Entity roster | brand_label withheld. | Included. |
/v1/coverage | ticker and status, plus metric_coverage_issue, held_metrics and complete_tail_scope when metric-hold metadata is present. Post-embargo freshness and volume fields are withheld. | All fields. |
| Subscription extras | None. | /v1/quality, /v1/trends/{trend_id}/scores, data_quality and company_freshness in /v1/status. |
| Bulk drops | Trial drops, cut at the embargo. | Full drops. |
| Limits | The same burst guard and bulk-job cap for both. See limits. | |
Trial brand and entity ids are the subscription's ids, so a model built on a trial carries over unchanged.
X default corrections remove selected event effects. With correct=recommended (the default), corrected replaces meme, incident, investor and marketing spikes with the stored corrected estimate. Genuine demand_event days are retained. Use correct=none to keep every spike, and compare raw alongside corrected.
History works differently by dataset. X company metrics keep dated versions (kdate) from launch; earlier history is reconstructed. Google search company series, company history and search trends keep recorded snapshots and take kdate from 2026-11-04 Eastern onward; earlier history is reconstructed. /v1/search/brands, /v1/search/trends/map and bulk ZIPs serve the latest only and reject kdate. Ownership windows govern which brands count toward a company. See Google search at a kdate.
The coverage numbers aren't interchangeable — count each one on its own. The X universe includes delisted and acquired companies, so filter by coverage_status and count unique company_id for what's live today. Google-search companies, brands and trends are separate populations; get current figures from search_coverage.csv in the latest bulk drop and /v1/search/trends, and note the date and filters with any count.
Quick start
Four calls: check your key and the data date, resolve a ticker, pull X demand, pull Google search interest.
export LIKEFOLIO_API_KEY="<YOUR_API_KEY>"
BASE=https://data.likefolio.com/v1
H="Authorization: Bearer $LIKEFOLIO_API_KEY"
# 1. your tier, embargo cutoff and each dataset's source as_of; use company search complete_through for current search windows
curl -s -H "$H" "$BASE/status"
# 2. a ticker to its stable company_id (key everything by company_id)
curl -s -H "$H" "$BASE/resolve?ticker=CELH"
# 3. X company demand: one company line per day for purchase intent and mentions
curl -s -H "$H" "$BASE/company/CELH/metrics?metric=mentions,pi&rollup=ticker&start=2025-01-01&format=csv" -o celh_x.csv
# 4. Google search interest: the company line (sum of its verified brands)
curl -s -H "$H" "$BASE/company/NKE/search?rollup=ticker&start=2025-01-01&format=csv" -o nke_search.csv
import os, requests, pandas as pd
BASE = "https://data.likefolio.com/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['LIKEFOLIO_API_KEY']}"
def get_all(path, **params):
"""Every row of a paged JSON route: follow next_cursor until it is null."""
rows, cursor = [], None
while True:
r = S.get(f"{BASE}{path}", params={**params, **({"cursor": cursor} if cursor else {})}, timeout=60)
r.raise_for_status()
body = r.json()
rows += body["data"]
cursor = body.get("next_cursor")
if not cursor:
return pd.DataFrame(rows), body
status = S.get(f"{BASE}/status", timeout=30).json()
x, env = get_all("/company/CELH/metrics", metric="mentions,pi", rollup="ticker", start="2025-01-01")
wide = x.pivot_table(index="date", columns="metric", values="corrected")
search, senv = get_all("/company/NKE/search", rollup="ticker", start="2025-01-01")
print(env["as_of"], senv["complete_through"], senv["coverage"])
The X company routes take the numeric company_id or a ticker in the path; the search route takes a ticker. Tickers are point-in-time aliases, so for anything long-lived resolve once and key by company_id. See identifiers.
The response envelope
Every JSON response wraps its rows in the same envelope. Routes add their own fields after these (for example the search routes' coverage).
{
"as_of": "2026-10-31", // the dataset's latest data day behind this response
"embargo_cutoff": "2026-05-01", // trial keys: the last date served; null on subscription
"tier": "trial",
"dataset": "company_demand",
"schema_version": "2026-09",
"rows": 2, // rows in this page
"next_cursor": null, // pass back unchanged for the next page; null when done
"data": [ { … }, { … } ]
}
Values above are illustrative. as_of is a dataset-wide date, not a promise that every returned series reaches it.
Formats and paging
| Format | What you get |
|---|---|
json | The envelope above. Up to 50,000 rows a page; follow next_cursor until it is null. |
csv | A header row and the rows, no envelope. Paging and labels travel in headers: x-next-cursor, x-embargo-cutoff, and per route x-release-id, x-truncated-to, x-complete-through, x-search-coverage. Counts are written as integers (210, never 210.0). |
parquet / arrow | The whole result as one file attachment (application/vnd.apache.parquet, or an Arrow IPC file as application/vnd.apache.arrow.file). Columns keep their JSON types: integers int64 with nulls, fractional numbers double, booleans bool, strings string. The envelope is the file's key-value metadata and is repeated in the x-as-of, x-embargo-cutoff, x-tier, x-dataset, x-schema-version and x-rows headers. cursor is rejected with these formats. Each file is a bulk job (see limits). Trial keys may use them; the embargo applies. |
Cursors are opaque and bound to the query, tier and publication. Change any parameter, or cross a new publication, and you start again from the first page. Browsers can read every documented response header cross-origin.
Status and keys
GET /v1/status
Your tier, your embargo cutoff, and each published dataset's as_of and refresh time. For Google search, use each company response’s complete_through for current windows; dataset as_of is the source snapshot date.
| Field | Meaning |
|---|---|
tier, embargo_cutoff, schema_version | As in the envelope. |
key_prefix, requests_total | The first characters of your key, and its lifetime request count (not a quota). |
datasets | One row per published dataset: dataset, as_of, refreshed_at. |
api_version | The running API contract version. This is separate from the version recorded when an X publication was built. |
release | The current X company publication (its api_version is historical build metadata and may differ from the running API): release_id, as_of (its latest data day), api_version, schema_version, built_at, published_at, history_mode, default_corrections, and its capability flags. |
trends_release | The consumer-trends publication: through (the last day every trend series reaches), trends, published_at, history_mode. |
data_quality, company_freshness | Subscription only. The independent check of the current publication (as /v1/quality), and per-company freshness counts (latest_complete_day, companies_current, …). Use /v1/coverage for each company. |
curl -s -H "Authorization: Bearer $LIKEFOLIO_API_KEY" https://data.likefolio.com/v1/status
{
"tier": "subscription",
"embargo_cutoff": null,
"schema_version": "2026-09",
"datasets": [
{ "dataset": "company_demand", "as_of": "2026-10-24", "refreshed_at": "…" },
{ "dataset": "search_interest", "as_of": "2026-10-31", "refreshed_at": "…" },
…
],
"release": { "release_id": "…", "as_of": "2026-10-24", "api_version": "1.4.0", … },
"trends_release": { "through": "…", "trends": …, "published_at": "…", "history_mode": "…" }
}
Trimmed and illustrative. The datasets list names only what is published to you: X company demand (company_demand, cross_section), consumer trends (trend_catalog, trend_ticker_map, trend_series) and Google search interest (search_interest) and Google search trends (search_trends).
GET /v1/quality subscription
The independent verification of the current publication: status (passed, failed or unverified), ready, reason, and when available checked_at and issue_counts. It answers 200 only when a passing check of the current publication ran within the last three hours, and 503 otherwise. A trial key gets 403. A healthy service doesn't guarantee fresh data — this check does.
curl -s -H "Authorization: Bearer $LIKEFOLIO_API_KEY" https://data.likefolio.com/v1/quality
POST /v1/keys/rotate
Issues a new key for the key you call it with, and returns it once: {"key": "…", "old_key_stops_at": "…"}. The old key keeps working for 10 minutes, then answers 403 key revoked. No request body. If a team shares the key, agree who rotates it, and update every user within those 10 minutes.
curl -s -X POST -H "Authorization: Bearer $LIKEFOLIO_API_KEY" https://data.likefolio.com/v1/keys/rotate
Lost or exposed a key? Rotate it, or ask us to revoke it.
All endpoints
Google-search as_of is the source snapshot date, not a completeness guarantee. It can be intraday and doesn't mean every company is complete through that day. Use each company response's complete_through for that; the history route returns complete_through=null.
Opaque pagination cursors
Treat next_cursor and x-next-cursor as opaque strings: pass them back unchanged, without decoding or constructing them. Continue with the same endpoint, parameters, format and key tier. Company-search cursors also bind to the current publication and embargo cutoff. A publication, query, format or tier change returns HTTP 400 with field=cursor; discard the unfinished pagination result and restart without a cursor. Current company search and explicit-history company search have separate cursor contexts: one route’s cursor cannot continue the other.