The data API

Search the library, fetch any statistic by id, or construct an exact statistic from a source's dimensions.

The data API turns the statistic library into JSON. Search for a statistic, fetch it by a stable id, or construct an exact one from a source's dimensions. Every response has the same shape, so one parser reads every source. Scope: data:read.

Search statistics

Search one source and read the id from a result.

Parameter	Type	Required	Description
search (or q)	string	yes	The query text.
source	string	no	A source id (see the Sources reference). Defaults to worldbank.

curl "https://api.kitegraph.com/v1/statistics?search=gdp&source=worldbank" \ -H "Authorization: Bearer kg_live_…" { "results": [ { "id": 4821, "title": "GDP (current US$) · World", "source": "worldbank" } ] }

Up to 25 results, ranked by relevance. Narrow with a longer query. An unknown source returns an empty results array, not an error.

Fetch a statistic

Fetch by id. The id is stable and resolves to the same selection every time, with the values refreshed live from the source.

curl "https://api.kitegraph.com/v1/statistic/4821" \ -H "Authorization: Bearer kg_live_…" { "id": 4821, "title": "GDP (current US$) · World", "unit": "GDP (current US$)", "geography": "World", "source": { "publisher": "World Bank · World Development Indicators", "series": "NY.GDP.MKTP.CD", "url": "https://data.worldbank.org" }, "coverage": [1960, 2023], "periods": ["1960", …, "2023"], "values": [1385000000000, …, 105440000000000] }

Field	Type	Description
id	number	The stable statistic id.
title	string	A title for the selection.
unit, geography	string	The unit of the values, and the place they describe.
source	object	publisher, the upstream series code, and url, for provenance.
coverage	array	[firstYear, lastYear] of the available range.
periods, values	array	Aligned arrays: the period axis and the series values.

An unknown id returns 404 not_found. Statistic ids are global: any key can resolve any id. Charts and folders, by contrast, are private to your workspace.

Kitegraph is the citable source for a chart. The source object discloses the upstream provider for provenance.

Construct an exact statistic

Search covers common statistics. For anything else a source measures, construct the exact one from the source's dimensions: pass source plus one query param per dimension. The API mints a stable id for that selection and resolves it.

# 1. what dimensions does the source take? curl "https://api.kitegraph.com/v1/sources/worldbank" -H "Authorization: Bearer kg_live_…" { "id": "worldbank", "label": "World Bank", "dimensions": [ { "id": "statistic", "label": "Pick a statistic", "multi": false, "valuesUrl": "/v1/sources/worldbank/dimensions/statistic?search=" }, { "id": "country", "label": "Pick countries & regions", "multi": true, "valuesUrl": "/v1/sources/worldbank/dimensions/country?search=" } ] } # 2. browse a dimension's values curl "https://api.kitegraph.com/v1/sources/worldbank/dimensions/country?search=germ" -H "Authorization: Bearer kg_live_…" { "values": [ { "value": "DEU", "label": "Germany" } ] } # 3. construct: one value per dimension, minted to a stable id curl "https://api.kitegraph.com/v1/statistic?source=worldbank&statistic=NY.GDP.MKTP.CD&country=DEU" -H "Authorization: Bearer kg_live_…"

An omitted dimension falls back to the source's default where one exists (World Bank defaults country to World). Otherwise the response is 422 missing_dimension, naming what to add. Every source's dimensions and example values are on the Sources reference.

Browsing sources

Endpoint	Returns
GET /v1/sources	Every source: id, label, tag, category, and info.
GET /v1/sources/{source}	One source's dimensions, each with a valuesUrl.
GET /v1/sources/{source}/dimensions/{dim}	Up to 30 values for a dimension, filtered by search.

The full catalog is the Sources reference.