API for developers
The data behind value.today as a simple JSON API: rankings, financials as reported and as first reported, ownership, filings, identifiers, survivorship-bias-free samples and economic first prints for 50,000+ companies.
Quick start
Send your key in the X-API-Key header (or Authorization: Bearer …). Amounts are in USD millions.
curl -H "X-API-Key: vt_your_key" "https://www.value.today/api/v1/companies?country__slug=india&ordering=-revenue" curl -H "X-API-Key: vt_your_key" "https://www.value.today/api/v1/ask?q=largest+banks+in+europe"
import requests
r = requests.get("https://www.value.today/api/v1/companies/apple", headers={"X-API-Key": "vt_your_key"})
apple = r.json()
print(apple["rank"], apple["market_cap"], apple["ownership"]["subsidiary_count"])In a spreadsheet: Google Sheets functions and an Excel query. Signed in, you can make keys and see their usage on API keys and usage.
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (the quota resets at midnight UTC). Over the limit you get HTTP 429 with Retry-After.
For research
Point-in-time statements, survivorship-bias-free samples, identifiers and first prints, from your own code.
Python (requests and pandas):
import requests, pandas as pd
API, H = "https://www.value.today/api/v1", {"X-API-Key": "vt_your_key"}
# Apple's statements as they stood on 30 June 2015 (point in time: only what had been filed by then)
s = requests.get(f"{API}/companies/apple/financial-statements/", params={"as_of": "2015-06-30", "years": 10}, headers=H).json()
# S&P 500 members on 15 September 2008, the companies that left since included
m = requests.get(f"{API}/research/index-members/", params={"index": "SPX", "date": "2008-09-15"}, headers=H).json()
members = pd.json_normalize(m["members"])
# Tickers, CIKs, ISINs or LEIs to value.today companies with all their identifiers
ids = requests.get(f"{API}/research/identifiers/", params={"ids": "AAPL,US0378331005,0000320193"}, headers=H).json()R (httr2):
library(httr2)
vt <- function(path, ...) request("https://www.value.today/api/v1") |> req_url_path_append(path) |> req_url_query(...) |>
req_headers(`X-API-Key` = Sys.getenv("VT_API_KEY")) |> req_perform() |> resp_body_json(simplifyVector = TRUE)
payrolls <- vt("economy/revisions/us-payrolls/", as_of = "2020-05-01") # the series as published that day
head(payrolls$as_of$rows)
restated <- vt("research/restatements/", line = "revenue", year = 2018)
head(restated$largest)Stata:
* Stata 16 or later, through its Python
python:
import requests, pandas as pd
r = requests.get("https://www.value.today/api/v1/research/delisted/", params={"country": "US"}, headers={"X-API-Key": "vt_your_key"}).json()
pd.json_normalize(r["results"])[["name", "ticker", "last_market_cap", "last_market_cap_date", "reason_label"]].to_stata("delisted.dta", write_index=False)
end
use delisted.dta, clearEvery endpoint is described in OpenAPI 3.1 at https://www.value.today/api/v1/openapi/ (no key needed), for generating a client. Definitions, formulas and sources of every figure are on the methodology page; cite the data with the day you fetched it.
Endpoints
39 endpoints, version 1.2
Companies
- GET/companies/
Companies, ranked Listed and unlisted companies, largest first. Amounts in USD millions.
country__slug · sector__slug · industry__slug · listing_status · market_cap_min · search · ordering · updated_since · page
- GET/companies/{slug}/
One company Profile, financial history in USD, quarterly results, filings, people, rank history, sources, ownership and industry benchmarks.
- GET/companies/{slug}/financial-statements/
Financial statements as reported, point in time Income statement, balance sheet and cash-flow statement by fiscal year and quarter, in the reported currency and full units, each figure with its filing and XBRL concept. A figure changed after its first report carries its first value and filing. Definitions: https://www.value.today/methodology#as-first-reported
basis · as_of · years · quarters
- GET/search/
Search companies, people, funds, brands, indices, countries and pages Typo-tolerant: a name, part of one, a ticker, an ISIN, an LEI or a CIK. `results` are the best matches in order, each with its kind and the page it leads to; `groups` the same by kind (with per_group or type).
q · limit · type · per_group
- GET/ask/
A question in plain English Answered from the database by rules (no language model).
q
Groups
- GET/countries/
Totals by country
- GET/sectors/
Totals by sector
- GET/world/
Market cap by country, continent and sector
Market caps
- GET/rankings/snapshot-dates/
The dates of the market-cap snapshots since 2020
- GET/rankings/snapshot/
The ranking at one snapshot, delisted companies included Every company valued at that snapshot, including those that have since left the market.
date · limit
People and deals
- GET/leaders/
Business leaders and billionaires
- GET/deals/
Acquisitions
- GET/startups/
Startups and their funding
Filings
- GET/filings/latest/
The newest SEC filings
type
Currencies
- GET/fx/
Today's exchange rates used for conversions (units per USD)
- GET/exchange-rates/
Every currency against the US dollar: the list
- GET/exchange-rates/{code}/
One currency by month and year Average and end-of-period rates against the US dollar (BIS) and the World Bank's yearly conversion factors. Definitions: https://www.value.today/methodology#average-exchange-rates
Research
- GET/research/restatements/
Restatements: figures changed after their first report Rates by line and fiscal year, and the largest changes with both filings. Definitions: https://www.value.today/methodology#as-first-reported
line · year · direction
- GET/research/identifiers/
Identifier lookup (crosswalk) Companies for a list of tickers, SEC CIKs, ISINs, LEIs, Wikidata items or names, with every identifier they carry. Definitions: https://www.value.today/methodology#identifier-lookup
ids
- GET/research/index-members/
An index's members on any day Today's members with every recorded change since undone; unmatched additions are listed. Definitions: https://www.value.today/methodology#index-members-on-a-date
index · date
- GET/research/delisted/
Delisted companies and how they left Definitions: https://www.value.today/methodology#delisted-companies
reason · country · q · page
- GET/indices/{code}/changes/
Additions to and removals from an index From Wikipedia's historical-components tables (CC BY-SA 4.0: attribute and share alike). Definitions: https://www.value.today/methodology#index-changes
- GET/methodology/
Every metric's definition, formula, sources, schedule and coverage
- GET/datasets/
The research datasets: each with its newest file's rows, size and SHA-256, and the versions The files themselves are downloaded on /datasets by accounts with the download right. Definitions: https://www.value.today/methodology#research-datasets
- GET/datasets/{key}/
One dataset's data dictionary, sources, terms, versions and first rows Definitions: https://www.value.today/methodology#research-datasets
version
Economy
- GET/economy/
The latest figure of every major US release
- GET/economy/series/{key}/
One economic series Values, its main presentations, first prints and revisions.
- GET/economy/revisions/
How much US first prints are revised Definitions: https://www.value.today/methodology#first-print-revisions
since
- GET/economy/revisions/{key}/
One series' first prints, and the series as published on any day Definitions: https://www.value.today/methodology#first-print-revisions
since · as_of
- GET/economy/calendar/
When the US releases come out
- GET/indicators/
The World Bank, IMF and BIS indicator catalogue Names and coverage; the values of IMF series are not served to API keys (the IMF's terms).
q · topic · source
- GET/indicators/{code}/
One indicator for every country, by year World Bank (CC BY 4.0) and BIS series; IMF series are refused to API keys.
c
- GET/trade/
Exports and imports of every country: the list
- GET/trade/{country}/{flow}/
One country's exports or imports by year, partner and product World Bank, WITS, CEPII BACI and the Harvard Growth Lab, each row naming its source.
Status
- GET/status/
Whether the site, the API and each data feed work now The data feeds' newest dates against their schedules, the data jobs of the last day and 30 days, and value.today's notices about incidents and maintenance. Needs no key.
Sync
- GET/changes/
What changed since a moment Companies changed (and the address that lists them with updated_since), companies merged or removed, and the loads and edits of the period with their counts. Pass the answer's until as since next time. Up to 90 days back.
since
Spreadsheets
- GET/sheets/values/
The latest figures of up to 100 companies, ready for a spreadsheet Companies by ticker, ISIN, CIK, LEI, Wikidata item, exact name or value.today slug (the largest match wins); fields by key, label or alias. Each row carries its market cap's date and its statements' fiscal year. as=table gives one array of rows with a header row; as=text the one value alone (one company, one field). A team key may name one of its lists instead.
companies · fields · list · as
- GET/sheets/history/
One yearly figure of one company over the years Each year with its fiscal year end and its source (SEC, ESEF, the editors, Wikidata citing the annual report, market caps).
company · field · years · as
- GET/sheets/fields/
Every field the spreadsheet endpoints know With its unit and the methodology entry that defines it.
Terms
- Show “Data: value.today” with a link when you publish the data.
- Figures come from official filings, registers, Wikidata and market data; each company lists its sources. They are for information only, not investment advice.
- Don't share your key or put it in public web pages; ask for a new one if it leaks.
Plans
- Free1,000 requests a day
- Pro50,000 requests a day
- Enterprise1,000,000 requests a day, bulk files and custom fields
For Pro or Enterprise, write to administrator@value.today with your key's first characters.