LikeFolio Data
LikeFolio Data · API docs

Data concepts read this once

The rules behind every response: what the ids promise, what "verified" means, how weekly and daily rows are labelled, how ownership windows clip a series, which date to anchor on, and how corrections reach you.

Identifiers

IdExampleWhat it promises
company_id6 (Apple)The stable company key, a string. It does not change when a ticker is renamed or re-listed, so key everything long-lived by it. Get it from /v1/resolve or /v1/universe.
tickerCELHA point-in-time alias, not a key. ticker is the ticker at kdate; ticker_at_date is the ticker on the row's own date, blank where the dated history does not reach (a symbol can belong to another security earlier). source_ticker is the stable input-family name.
entity_idAAL, COIN#deribit, AAPL#music-audio-streamingOne company's business in one category. A company with one live entity uses the bare ticker; a carved-out brand is TICKER#brand-slug; any other division is TICKER#division-slug. Ids come from an append-only registry: an id, once shipped, never changes. URL-encode # as %23 in query strings.
perm_id, figi, share_class_figi4295905573, BBG000B9XRY4External ids, observed from 2026-09-23 onward, null when unknown. FIGIs are checked against OpenFIGI; permIDs are as supplied by the source. Resolve one to a company_id first, then query by company_id.
trend_idT011Permanent, and shared by the X trends and the Google search trends: the same id is the same behaviour in both. A trend keeps its id when renamed (responses carry the current name); a retired trend's id is never reused.
brand_idNKE#b7A Google-search brand, numbered per ticker. Permanent: a brand keeps its number however volumes move, a new brand takes the ticker's next number, and no number is reused. Numbers have gaps in what you receive, because brands that are not verified also hold numbers. Trial keys see only these ids; subscription keys get the names, and /v1/search/brands lists both.

Verified brands and coverage (search)

We publish a Google search brand only after checking it against Google's own data. For every brand we take Google's 5-year weekly series for the same search term, pulled directly from Google Trends, and compare it with ours week by week. The brand is verified when all of these hold:

We also hold back generic words whose searches mostly do not measure the company (a word that is both a brand name and an everyday term), even when they match Google. Brands that do not pass are not published; they stay in our research set until they are fixed and pass.

Coverage is the share of a company's total Google search interest over the last 365 days that comes from its verified brands. A coverage of 0.92 means the brands you receive account for 92% of the search interest we track for that company; the other 8% is in brands still being verified. A company is published only when its coverage is at least 0.25. Below that, or with no verified brand, the API answers 404 not covered.

Coverage is on every search response (coverage, coverage_full_history, verified_brands, candidate_brands; CSV headers x-search-coverage, x-search-verified-brands), on every /v1/search/brands row, and in the bulk drop's search_coverage.csv. When a brand becomes verified it is added with its full history, and the company's coverage moves.

Resolution labels (search)

Google reports some brands day by day and others only week by week. Each search brand row says which with resolution:

Rows also carry a per-day provenance field recording how each day's value was produced. You do not need it to use the data; resolution is the label to read.

Ownership windows

A company's numbers include a brand or division only while the company owns it. Each X entity and each search brand carries valid_from and valid_to (both days included; blank means open).

Data dates: as_of, complete_through, through

The data trails the calendar, and each dataset refreshes on its own schedule: consumer trends (X) daily, with the completed Eastern day published the next morning; company metrics (X) weekly, in a Sunday run; Google search interest daily, with a per-company complete_through. Anchor every "last N days" window on the data's date, never on today.

WhereFieldMeaning
/v1/status datasetsas_of, refreshed_atEach published dataset's latest data day and refresh time.
/v1/status releaseas_ofThe X company publication's latest data day. Also release_id, published_at.
/v1/status trends_releasethroughThe last day every trend series reaches.
Search responsescomplete_throughOne company's pipeline-estimated search cutoff; not a guarantee of every expected member.
Every envelopeas_ofThe dataset's date, not a promise that every series in the response reaches it.

When end is later than the last day a response can serve, it stops there and says so: truncated_to and requested_end in JSON (requested_date on cross-sections), x-truncated-to on CSV. A "last 28 days to today" request can hold fewer than 28 days; do not compare it with a full 28-day base.

Trial embargo. Trial keys see everything up to embargo_cutoff, six months before today, and nothing after. A request entirely after the cutoff is 416.

Point-in-time reads by dataset

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 date axis is the event day. A second axis, the knowledge date, selects what LikeFolio had published by a given day, with no look-ahead through later restatements or M&A. Routes that take it: /v1/universe, /v1/resolve, /v1/crosswalk, /v1/company/{companyId}/entities, /v1/company/{companyId}/metrics, the cross-sections and four Google search routes. The table below describes the X routes; Google search takes only kdate and history_mode.

ParameterMeaning
kdateYYYY-MM-DD: the publication known at the end of that Eastern day, and the ownership on that day. Omit it for the latest. A future kdate is 416. On company metrics, kdate=all returns every recorded vintage, each row with its own release_id and half-open [kdate_from, kdate_to) interval.
observed_atAn optional timezone-bearing instant on kdate, for an intraday cut. Not with kdate=all.
release_idPin one publication from /v1/publications. It cannot be later than kdate.
history_modeauto (default), recorded (refuse anything before go-live) or reconstructed (only before go-live).

Before go-live there is one vintage. Recorded vintages run from the publication launch (publication_launch_at in /v1/status) forward. A kdate before it is served from the as-built reconstruction and labelled history_mode: reconstructed with a reconstruction_note. That reconstruction may use observations made after the kdate, so it is not a no-look-ahead backtest of the historical methodology. Use kdate vintages to walk forward through M&A and later corrections from go-live on.

Every point-in-time route also sends x-release-id, x-history-mode, x-kdate-from and (reconstructions only) x-reconstruction-note headers, so a CSV keeps its label.

# Apple's mentions for May 2023, as LikeFolio had them on 2023-06-01
curl -s -H "Authorization: Bearer $LIKEFOLIO_API_KEY" \
  "https://data.likefolio.com/v1/company/6/metrics?metric=mentions&kdate=2023-06-01&start=2023-05-01&end=2023-05-31"

# every recorded vintage of Apple's mentions
curl -s -H "Authorization: Bearer $LIKEFOLIO_API_KEY" \
  "https://data.likefolio.com/v1/company/6/metrics?kdate=all&metric=mentions&format=csv"

Search interest, trends and bulk drops serve the latest publication only and reject the time-travel parameters.

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. Request correct=none to retain those optional event effects in the mandatory cleaned baseline, and compare raw alongside corrected.

Corrections: raw, corrected, flag

Observed, filled and transformed values. Some values are filled or rescaled rather than read straight from Google. The provenance and resolution columns tell you which: lf_fill marks a value we filled in, and weekly values may be spread across daily rows. A missing row means no data, not zero.

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.

Google search is recorded from its first snapshot, captured 2026-11-05T04:20:42Z, which is 23:20 Eastern on 2026-11-04. That makes 2026-11-04 the first recorded kdate. Earlier history is reconstructed from that snapshot and labelled. Without kdate these routes are unchanged and serve the latest snapshot.

Routekdate and history_mode
/v1/company/{ticker}/searchSupported
/v1/company/{ticker}/search/historySupported
/v1/search/trendsSupported
/v1/search/trends/{trend_id}/seriesSupported
/v1/search/brands, /v1/search/trends/mapNot supported at launch: 400
/v1/bulk and bulk ZIPsNot supported at launch: 400 on the listing, and no ZIP is a dated snapshot

observed_at, release_id and kdate=all are not offered on any Google search route and answer 400. history_mode without kdate also answers 400. Google search has no superseded_by on these reads.

A reconstructed read is not what was published that day. It has no row dated after kdate, but its values, brands and ownership windows are as recorded in the first snapshot. A row can carry a valid_to for a sale that had not happened by kdate; the row values and which brands are summed for a date stay correct. coverage, coverage_full_history, verified_brands, candidate_brands and closed_calendar_day are omitted, because they are as of the capture.

A reconstructed read includes the row dated kdate where the first snapshot has one, and complete_through on the company series is then kdate itself. A read made that day could not have held that row: no company series in the first snapshot, the one kdate 2026-11-04 reads, runs past 2026-11-03. A signal backtested on reconstructed reads therefore has a look-ahead of at least one day. X reconstructions use the same rule.

Held companies. The first snapshot holds 27 companies: 11 with an ended company registry and 16 for other reasons. On /v1/company/{ticker}/search each answers 404 search_series_held at every kdate read from a snapshot that holds it, including dates when the company was live. A reconstructed 404 says only that a hold exists. A backtest on that route therefore loses these companies, which is survivorship bias, and the 404 is itself later knowledge. Their rows are reachable only through /v1/company/{ticker}/search/history, whose baskets are not certified and which may hold legacy interpolated or carried values. Filter on the provenance column of brand rows before using them; a rollup=ticker line sums the brands and has no such column.

Recorded reads. Google rows, trend series, availability, maps, coverage and company identities come from the selected snapshot. Read live on each request, not from the snapshot: the row window of a company without a search identity record, the trial cutoff and, for the first snapshot, the trend id registry. If one of those moves, the same kdate can return different rows with the same kdate_from. A failed capture, or a day when the files did not change, writes no snapshot; that day reads the older one as recorded, with its older kdate_from. A kdate on the current Eastern day can change until the day closes, because a later capture that day becomes the selected snapshot, with a different kdate_from.

Before a series starts. A company read at a kdate before its first row is an empty 200. A trend read before its first_date is 404 with x-identifier-status: not_covered_at_kdate, and the catalog at that kdate does not list it. A company absent from the selected snapshot gets the same 404.

Trial keys. The embargo cutoff is computed from today, never from kdate, so no kdate moves it. Rows stop at the cutoff at every kdate, as_of, complete_through and catalog last_date are capped at it, a closed_calendar_day past it is dropped, and a trend that starts after it is not listed. A range entirely after the cutoff is 416. Dates can still pass the cutoff in two places, neither a value: a row's valid_to as recorded, and the labels kdate_from, kdate_to, recorded_from and release_id, which name capture times.

Integrity. A snapshot that fails its hash check answers 503. There is no fallback to another snapshot or to the latest data.

# CALY's company line as of 2025-12-01, reconstructed and labelled
curl -s -H "Authorization: Bearer $LIKEFOLIO_API_KEY" \
  "https://data.likefolio.com/v1/company/CALY/search?rollup=ticker&kdate=2025-12-01&start=2025-11-01"

Restatements and changes

Recorded X company publications retain their publication history; Google search keeps recorded snapshots from kdate 2026-11-04 Eastern and, without kdate, serves the current rebuilt snapshot. For X company publications, summary statistics (trend scores) and catalog counts (mapped_tickers, mapped_datasets) are recomputed daily. Restatements are never silent:

Event time is not availability time. Weekly values show when people searched, not when we received the data. Before the first recorded snapshot (kdate 2026-11-04 Eastern), search history is reconstructed from the latest data rather than a true point-in-time record; from that date on, each day's snapshot is kept.

Search aliases are dataset-specific. The two mapped search companies use company-lifetime aliases and optional JSON identity metadata; X dated ticker resolution is unchanged. See search company identity. Private storage identifiers are not public aliases.

Source snapshot date is not completeness. The search_interest entry in /v1/status.datasets reports as_of as the source snapshot date, which may be intraday. It is not a global complete day. Status does not provide a Google-search complete_through field. Use each current company response’s complete_through for its closed-UTC, active-basket endpoint; the history route returns complete_through=null.

Publication-scoped metric holds. Missing held behavior counts are null, never zero; complete-tail metadata may apply only to unheld metrics. Older recorded vintages retain their old values and no retrospective hold annotation. See metric-hold fields and headers.