Skip to content

Grapher Chart API

Our chart API is structured around charts on our website, i.e. at https://ourworldindata.org/grapher/* . You can find charts by searching our data catalog at https://ourworldindata.org/data.

Once you've found the chart with the data you need, simply append ".csv" to the URL to download the data or ".metadata.json" to retrieve the metadata. You can also add ".zip" to download a ZIP file that includes both files, along with a README in markdown format describing the data.

An example for our life expectancy chart:

Example notebooks

Check out this list of public example notebooks that demonstrate the use of our chart API:

API Information

Version: 1.0.0

Base URL: https://ourworldindata.org — Production server

License: CC BY 4.0

GET /grapher/{slug}

Get chart HTML page

Returns the full HTML page for a specific chart.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
tab string (table, map, chart, line, scatter, stacked-area, discrete-bar, stacked-discrete-bar, slope, stacked-bar, marimekko) Active tab for the chart
Example: map
country string Selected countries/entities. Can be a single entity or multiple separated by ~ (tilde) or + (plus).
Also supports special selectors like ~OWID_WRL (World).
Example: United States~China
mapSelect string Entity to highlight on the map. Can be multiple entities separated by ~ (tilde).
Example: France
time string Time period to display. Can be a single year (2020), a range (2000..2020), latest, or earliest.
Example: 2000..2020
nocache string If present, bypasses the cache
focus string Focused series names (separated by ~ or +)
overlay string (download-data, download-vis, sources) Open a modal overlay
stackMode string (absolute, relative) Stacking mode for charts
zoomToSelection string (true) Zoom to selected entities
xScale string (linear, log) X-axis scale type
yScale string (linear, log) Y-axis scale type
region string (World, Africa, NorthAmerica, SouthAmerica, Asia, Europe, Oceania) Map region
endpointsOnly string (0, 1) Show only endpoints (1 to enable)
facet string (none, entity, metric) Faceting strategy
uniformYAxis string (0, 1) Use uniform Y axis across facets (1 to enable)
showNoDataArea string (0, 1) Show "No data" area in stacked charts (1 to enable)
globe string (0, 1) Enable globe view (1 to enable)
globeRotation string Globe rotation (lat,lon)
globeZoom number Globe zoom level
tableFilter string Filter string for the data table
tableSearch string Search string for the data table

Responses

✅ 200 - Successful response

Content-Type: text/html

❌ 404 -

GET /grapher/{slug}.{format}

Get chart as PNG or SVG

Returns a PNG or SVG image of the chart.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
format string (png, svg) ✓ Image format (png or svg)
imType string (twitter, og, thumbnail, square, uncaptioned) Image type/preset
Example: og
imWidth integer Width of the generated image in pixels
imHeight integer Height of the generated image in pixels
imDetails string (0, 1) Include details (1 to enable)
imFontSize integer Font size for the image
imMinimal string (0, 1) Minimal mode (1 to enable). Affects thumbnails and uncaptioned images.
imSquareSize integer Size for square images
nocache string If present, bypasses the cache
tab string (table, map, chart, line, scatter, stacked-area, discrete-bar, stacked-discrete-bar, slope, stacked-bar, marimekko) Active tab for the chart
Example: map
country string Selected countries/entities. Can be a single entity or multiple separated by ~ (tilde) or + (plus).
Also supports special selectors like ~OWID_WRL (World).
Example: United States~China
time string Time period to display. Can be a single year (2020), a range (2000..2020), latest, or earliest.
Example: 2000..2020
focus string Focused series names (separated by ~ or +)
stackMode string (absolute, relative) Stacking mode for charts
zoomToSelection string (true) Zoom to selected entities
xScale string (linear, log) X-axis scale type
yScale string (linear, log) Y-axis scale type
region string (World, Africa, NorthAmerica, SouthAmerica, Asia, Europe, Oceania) Map region
endpointsOnly string (0, 1) Show only endpoints (1 to enable)
facet string (none, entity, metric) Faceting strategy
uniformYAxis string (0, 1) Use uniform Y axis across facets (1 to enable)
showNoDataArea string (0, 1) Show "No data" area in stacked charts (1 to enable)
globe string (0, 1) Enable globe view (1 to enable)
globeRotation string Globe rotation (lat,lon)
globeZoom number Globe zoom level

Responses

✅ 200 - Chart image

Content-Type: image/png

Content-Type: image/svg+xml

❌ 404 -

GET /grapher/{slug}.csv

Get chart data as CSV

Returns the data used in the chart as a CSV file.

CSV Structure:

Each row in the CSV file corresponds to an observation for an entity (most often a country or region) at a specific time point (generally a year).

Columns:

The first two columns in the CSV file are "Entity" and "Code."

  • Entity: The name of the entity, typically a country, such as "United States."
  • Code: The OWID internal entity code used for countries or regions. For standard countries, this matches the ISO alpha-3 code (e.g., "USA"); for non-standard or historical countries, we use custom codes. Country and region names are standardized across all Our World in Data datasets, allowing you to join multiple datasets using either of these columns.
  • Year or Day: If the data is annual, this is "Year" and contains only the year as an integer. If the column is "Day", it contains a date string in the form "YYYY-MM-DD".
  • Data columns: The time series that powers the chart. Simple line charts have a single data column, while more complex charts can have multiple columns.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
v integer Version number (e.g., 1)
csvType string (full, filtered) Type of CSV to return:
  • full (default): Get the full data, i.e. all time points and all entities
  • filtered: Get only the data needed to display the visible chart. Different chart types return different subsets of the full data. For a map this will download data for only a single year but all countries, for a line chart it will be the selected time range and visible entities and so on for other chart types.

Note: If you use filtered, the other query parameters in the URL will change what is downloaded. E.g., ?csvType=filtered&time=1980..2000&country=~ITA
default: full
useColumnShortNames boolean Use short names for columns:
  • false (default): Column names are long, use capitalization and whitespace - e.g. Period life expectancy at birth - Sex: all - Age: 0
  • true: Column names are short and don't use whitespace - e.g. life_expectancy_0__sex_all__age_0

default: True
nocache string If present, bypasses the cache

Responses

✅ 200 - CSV data

Content-Type: text/csv

Request: GET https://ourworldindata.org/grapher/life-expectancy.csv

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.csv"

import requests

params = {}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.csv", params=params)
data = response.text

const response = await fetch("https://ourworldindata.org/grapher/life-expectancy.csv");
const data = await response.text();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.csv")
    .await?
    .text()
    .await?;

Entity,Code,Year,Period life expectancy at birth - Sex: all - Age: 0
Afghanistan,AFG,1950,27.7275
Afghanistan,AFG,1951,27.9634
Afghanistan,AFG,1952,28.1992

Request: GET https://ourworldindata.org/grapher/life-expectancy.csv?csvType=filtered&country=USA&time=2000..2020

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.csv?csvType=filtered&country=USA&time=2000..2020"

import requests

params = {
    "csvType": "filtered",
    "country": "USA",
    "time": "2000..2020"
}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.csv", params=params)
data = response.text

const params = new URLSearchParams({ csvType: "filtered", country: "USA", time: "2000..2020" });
const response = await fetch(`https://ourworldindata.org/grapher/life-expectancy.csv?${params}`);
const data = await response.text();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.csv")
        .query(&[("csvType", "filtered")])
        .query(&[("country", "USA")])
        .query(&[("time", "2000..2020")])
    .await?
    .text()
    .await?;

Entity,Code,Year,Period life expectancy at birth - Sex: all - Age: 0
United States,USA,2000,76.64
United States,USA,2010,78.54
United States,USA,2020,77.28
❌ 403 - Data is non-redistributable

Content-Type: application/json

Schema: Error

❌ 404 -

GET /grapher/{slug}.metadata.json

Get chart metadata

Returns metadata about the chart configuration and data.

The metadata includes:

  • chart: Chart configuration (title, subtitle, citation, etc.)
  • columns: Metadata for each data column (units, timespan, citations, etc.)
  • dateDownloaded: Timestamp of when the data was downloaded

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
nocache string If present, bypasses the cache

Responses

✅ 200 - Chart metadata

Content-Type: application/json

Example: Life expectancy chart metadata

Request: GET https://ourworldindata.org/grapher/life-expectancy.metadata.json

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.metadata.json"

import requests

params = {}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.metadata.json", params=params)
data = response.json()

const response = await fetch("https://ourworldindata.org/grapher/life-expectancy.metadata.json");
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.metadata.json")
    .await?
    .json::<serde_json::Value>()
    .await?;

Response schema: ChartMetadata

{
  "chart": {
    "title": "Life expectancy",
    "subtitle": "The [period life expectancy](#dod:period-life-expectancy) at birth, in a given year.",
    "citation": "UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005)",
    "originalChartUrl": "https://ourworldindata.org/grapher/life-expectancy",
    "selection": [
      "World",
      "Americas",
      "Europe",
      "Africa",
      "Asia",
      "Oceania"
    ]
  },
  "columns": {
    "Period life expectancy at birth - Sex: all - Age: 0": {
      "titleShort": "Life expectancy at birth",
      "titleLong": "Life expectancy at birth - Various sources – period tables",
      "descriptionShort": "The period life expectancy at birth, in a given year.",
      "descriptionKey": [
        "Period life expectancy is a metric that summarizes death rates across all age groups in one particular year.",
        "..."
      ],
      "shortUnit": "years",
      "unit": "years",
      "timespan": "1543-2021",
      "type": "Numeric",
      "owidVariableId": 815383,
      "shortName": "life_expectancy_0__sex_all__age_0",
      "lastUpdated": "2023-10-10",
      "nextUpdate": "2024-11-30",
      "citationShort": "UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005) – with minor processing by Our World in Data",
      "citationLong": "UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005) – ...",
      "fullMetadata": "https://api.ourworldindata.org/v1/indicators/815383.metadata.json"
    }
  },
  "dateDownloaded": "2024-10-30"
}
❌ 404 -

GET /grapher/{slug}.readme.md

Get chart README

Returns a README markdown file for the chart data.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
nocache string If present, bypasses the cache

Responses

✅ 200 - README file

Content-Type: text/markdown

Example: Life expectancy README

Request: GET https://ourworldindata.org/grapher/life-expectancy.readme.md

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.readme.md"

import requests

params = {}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.readme.md", params=params)
data = response.text

const response = await fetch("https://ourworldindata.org/grapher/life-expectancy.readme.md");
const data = await response.text();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.readme.md")
    .await?
    .text()
    .await?;

# Life expectancy - Data package

This data package contains the data that powers the chart ["Life expectancy"](https://ourworldindata.org/grapher/life-expectancy) on the Our World in Data website.

## CSV Structure

The high level structure of the CSV file is that each row is an observation for an entity (usually a country or region) and a timepoint (usually a year).

The first two columns in the CSV file are "Entity" and "Code". "Entity" is the name of the entity (e.g. "United States"). "Code" is the OWID internal entity code that we use if the entity is a country or region.

The third column is either "Year" or "Day". If the data is annual, this is "Year" and contains only the year as an integer. If the column is "Day", the column contains a date string in the form "YYYY-MM-DD".

The final column is the data column, which is the time series that powers the chart.
❌ 404 -

GET /grapher/{slug}.zip

Get chart data ZIP

Returns a ZIP file containing CSV data, metadata, and README.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
nocache string If present, bypasses the cache

Responses

✅ 200 - ZIP file

Content-Type: application/zip

❌ 403 - Data is non-redistributable

Content-Type: application/json

Schema: Error

❌ 404 -

GET /grapher/{slug}.config.json

Get grapher config

Returns the raw configuration for the grapher chart.

The config follows the Grapher JSON schema.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
nocache string If present, bypasses the cache

Responses

✅ 200 - Grapher configuration

Content-Type: application/json

Example: Life expectancy config

Request: GET https://ourworldindata.org/grapher/life-expectancy.config.json

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.config.json"

import requests

params = {}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.config.json", params=params)
data = response.json()

const response = await fetch("https://ourworldindata.org/grapher/life-expectancy.config.json");
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.config.json")
    .await?
    .json::<serde_json::Value>()
    .await?;

{
  "id": 64,
  "slug": "life-expectancy",
  "title": "Life expectancy",
  "$schema": "https://files.ourworldindata.org/schemas/grapher-schema.010.json",
  "version": 62,
  "hasMapTab": true,
  "originUrl": "/life-expectancy",
  "isPublished": true,
  "variantName": "over the long-run",
  "yAxis": {
    "min": 0
  },
  "map": {
    "colorScale": {
      "baseColorScheme": "YlGnBu",
      "binningStrategy": "manual",
      "legendDescription": "Life expectancy (at birth)"
    },
    "timeTolerance": 10
  },
  "dimensions": [
    {
      "display": {
        "unit": "years",
        "shortUnit": "years",
        "numDecimalPlaces": 1
      },
      "property": "y",
      "variableId": 1118466
    }
  ],
  "selectedEntityNames": [
    "World",
    "Americas",
    "Europe",
    "Africa",
    "Asia",
    "Oceania"
  ]
}
❌ 404 -

GET /grapher/{slug}.values.json

Get data values

Returns data values for a specific entity.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
tab string (table, map, chart, line, scatter, stacked-area, discrete-bar, stacked-discrete-bar, slope, stacked-bar, marimekko) Active tab for the chart
Example: map
country string Selected countries/entities. Can be a single entity or multiple separated by ~ (tilde) or + (plus).
Also supports special selectors like ~OWID_WRL (World).
Example: United States~China
mapSelect string Entity to highlight on the map. Can be multiple entities separated by ~ (tilde).
Example: France
time string Time period to display. Can be a single year (2020), a range (2000..2020), latest, or earliest.
Example: 2000..2020
focus string Focused series names (separated by ~ or +)
stackMode string (absolute, relative) Stacking mode for charts
zoomToSelection string (true) Zoom to selected entities
xScale string (linear, log) X-axis scale type
yScale string (linear, log) Y-axis scale type
region string (World, Africa, NorthAmerica, SouthAmerica, Asia, Europe, Oceania) Map region
endpointsOnly string (0, 1) Show only endpoints (1 to enable)
facet string (none, entity, metric) Faceting strategy
uniformYAxis string (0, 1) Use uniform Y axis across facets (1 to enable)
showNoDataArea string (0, 1) Show "No data" area in stacked charts (1 to enable)
tableFilter string Filter string for the data table
tableSearch string Search string for the data table
nocache string If present, bypasses the cache

Responses

✅ 200 - Data values

Content-Type: application/json

Example: Life expectancy values for France

Request: GET https://ourworldindata.org/grapher/life-expectancy.values.json?country=France

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.values.json?country=France"

import requests

params = {
    "country": "France"
}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.values.json", params=params)
data = response.json()

const params = new URLSearchParams({ country: "France" });
const response = await fetch(`https://ourworldindata.org/grapher/life-expectancy.values.json?${params}`);
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.values.json")
        .query(&[("country", "France")])
    .await?
    .json::<serde_json::Value>()
    .await?;

Response schema: GrapherValuesJson

{
  "entityName": "France",
  "startTime": 1816,
  "endTime": 2023,
  "columns": {
    "1118466": {
      "name": "Life expectancy",
      "unit": "years",
      "shortUnit": "years"
    }
  },
  "startValues": {
    "y": [
      {
        "columnSlug": "1118466",
        "value": 40.1,
        "formattedValue": "40.1",
        "formattedValueShort": "40.1 years",
        "formattedValueShortWithAbbreviations": "40.1",
        "valueLabel": "40.1 years",
        "time": 1816,
        "formattedTime": "1816"
      }
    ]
  },
  "endValues": {
    "y": [
      {
        "columnSlug": "1118466",
        "value": 83.3,
        "formattedValue": "83.3",
        "formattedValueShort": "83.3 years",
        "formattedValueShortWithAbbreviations": "83.3",
        "valueLabel": "83.3 years",
        "time": 2023,
        "formattedTime": "2023"
      }
    ]
  },
  "source": "Riley (2005); Zijdeman et al. (2015); HMD (2025); UN WPP (2024)"
}
❌ 404 -

GET /grapher/{slug}.search-result.json

Get search results

Returns search results within the context of the chart.

Parameters

Parameter Type Required Description
slug string ✓ The URL slug of the chart
Example: population-density
version integer API version
default: 1
entities string Selected entities
variant string (Large, Medium) Data variant (Large or Medium)
numDataTableRowsPerColumn integer Number of rows per column in data table
default: 4
nocache string If present, bypasses the cache

Responses

✅ 200 - Search results

Content-Type: application/json

Example: Life expectancy search result

Request: GET https://ourworldindata.org/grapher/life-expectancy.search-result.json?variant=Medium

Code samples:

curl "https://ourworldindata.org/grapher/life-expectancy.search-result.json?variant=Medium"

import requests

params = {
    "variant": "Medium"
}
response = requests.get("https://ourworldindata.org/grapher/life-expectancy.search-result.json", params=params)
data = response.json()

const params = new URLSearchParams({ variant: "Medium" });
const response = await fetch(`https://ourworldindata.org/grapher/life-expectancy.search-result.json?${params}`);
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/grapher/life-expectancy.search-result.json")
        .query(&[("variant", "Medium")])
    .await?
    .json::<serde_json::Value>()
    .await?;

Response schema: GrapherSearchResultJson

{
  "title": "Life expectancy",
  "source": "Riley (2005); Zijdeman et al. (2015); HMD (2025); UN WPP (2024)",
  "grapherQueryParams": {
    "country": "OWID_WRL~Americas~OWID_EUR~OWID_AFR",
    "time": "1770..2023"
  },
  "layout": [
    {
      "slotKey": "single-slot",
      "grapherTab": "LineChart"
    },
    {
      "slotKey": "single-slot",
      "grapherTab": "Table"
    },
    {
      "slotKey": "single-slot",
      "grapherTab": "WorldMap",
      "chartParams": {
        "time": "2023"
      },
      "previewParams": {
        "time": "2023"
      }
    },
    {
      "slotKey": "small-slot-left",
      "grapherTab": "DiscreteBar"
    }
  ],
  "dataTable": {
    "rows": [
      {
        "seriesName": "Europe",
        "label": "Europe",
        "color": "#4c6a9c",
        "value": "79.1 years",
        "time": "2023",
        "timePreposition": "in",
        "muted": false,
        "striped": false
      },
      {
        "seriesName": "Americas",
        "label": "Americas",
        "color": "#c4523e",
        "value": "77.3 years",
        "time": "2023",
        "timePreposition": "in",
        "muted": false,
        "striped": false
      },
      {
        "seriesName": "World",
        "label": "World",
        "color": "#18470f",
        "value": "73.2 years",
        "time": "2023",
        "timePreposition": "in",
        "muted": false,
        "striped": false
      },
      {
        "seriesName": "Africa",
        "label": "Africa",
        "color": "#a2559c",
        "value": "63.8 years",
        "time": "2023",
        "timePreposition": "in",
        "muted": false,
        "striped": false
      }
    ],
    "title": "In years"
  },
  "valueDisplay": {
    "entityName": "World",
    "endValue": "73.2 years",
    "time": "2023",
    "showLocationIcon": false,
    "numericEndTime": 2023
  },
  "entityType": "country or region",
  "entityTypePlural": "countries and regions"
}
❌ 404 -

Schemas

Error

Properties
Property Type Required Description
error string ✓
message string

ChartMetadata

Metadata about the chart configuration and data columns.

Properties
Property Type Required Description
chart ChartMetadataChart ✓ Chart configuration metadata.
columns object ✓ Metadata for each data column, keyed by column name.
dateDownloaded string (date) ✓ Date when the data was downloaded (YYYY-MM-DD).
Example: 2024-10-30
activeFilters object Currently active query parameter filters.

ChartMetadataChart

Chart configuration metadata.

Properties
Property Type Required Description
title string Chart title.
Example: Life expectancy
subtitle string Chart subtitle, may contain markdown.
Example: The [period life expectancy](#dod:period-life-expectancy) at birth, in a given year.
note string Additional note displayed on the chart.
xAxisLabel string Label for the X axis.
yAxisLabel string Label for the Y axis.
citation string Citation/sources line.
Example: UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005)
originalChartUrl string (uri) Canonical URL of the chart.
Example: https://ourworldindata.org/grapher/life-expectancy
selection array[string] Default selected entities.
Example: World, Americas, Europe, ...

ChartMetadataColumn

Metadata for a single data column.

Properties
Property Type Required Description
titleShort string Short title for the column.
Example: Life expectancy at birth
titleLong string Full title including attribution.
Example: Life expectancy at birth - Various sources – period tables
descriptionShort string Brief description of the data.
descriptionKey array[string] Key points about the data methodology.
descriptionProcessing string Description of any processing applied to the data.
shortUnit string Short form of the unit (e.g., "years", "%").
Example: years
unit string Full unit name.
Example: years
timespan string Time range covered by the data.
Example: 1543-2021
tolerance integer Tolerance for time matching.
type string Data type of the column.
Example: Numeric
conversionFactor number Conversion factor applied to values.
owidVariableId integer Internal OWID variable identifier.
Example: 815383
shortName string Machine-readable short name.
Example: life_expectancy_0__sex_all__age_0
lastUpdated string (date) Date when the data was last updated.
Example: 2023-10-10
nextUpdate string (date) Expected date of next update.
Example: 2024-11-30
citationShort string Short citation for the data.
Example: UN WPP (2022); HMD (2023); Zijdeman et al. (2015); Riley (2005) – with minor processing by Our World in Data
citationLong string Full citation for the data.
fullMetadata string (uri) URL to the full indicator metadata.
Example: https://api.ourworldindata.org/v1/indicators/815383.metadata.json

GrapherValuesJson

Data values for a specific entity from a chart.

Properties
Property Type Required Description
entityName string Name of the entity.
Example: World
startTime integer Start time of the data range.
Example: 1950
endTime integer End time of the data range.
Example: 2021
columns object Column metadata, keyed by column slug.
startValues GrapherValuesJsonDataPoints Data points for a specific time.
endValues GrapherValuesJsonDataPoints Data points for a specific time.
source string Sources line for the chart.

GrapherValuesJsonColumn

Metadata for a single column in values response.

Properties
Property Type Required Description
name string Display name of the column.
unit string Unit of measurement.
shortUnit string Short form of the unit.
isProjection boolean Whether this column contains projected data.
yearIsDay boolean Whether the time column represents days instead of years.

GrapherValuesJsonDataPoints

Data points for a specific time.

Properties
Property Type Required Description
y array[GrapherValuesJsonDataPoint] Y-axis data points.
x GrapherValuesJsonDataPoint A single data point value.

GrapherValuesJsonDataPoint

A single data point value.

Properties
Property Type Required Description
columnSlug string ✓ Identifier of the column.
value any Raw value.
formattedValue string Human-readable formatted value.
formattedValueShort string Short formatted value.
formattedValueShortWithAbbreviations string Short formatted value with abbreviations (e.g., "1.2B").
valueLabel string Custom label for the value (e.g., from color scheme).
time integer Time of the observation.
formattedTime string Formatted time string.

GrapherSearchResultJson

Search result data for a chart, used for rich search previews.

Properties
Property Type Required Description
title string ✓ Chart title.
subtitle string Chart subtitle (plain text, markdown stripped).
source string ✓ Sources line (plain text).
grapherQueryParams object ✓ Query parameters to apply to the chart.
layout array[LayoutSlot] ✓ Layout slots for displaying chart tabs.
dataTable SearchDataTable ✓ Data table for search result display.
valueDisplay SearchValueDisplay Large value display for search results.
entityType string ✓ Singular entity type name.
Example: country
entityTypePlural string ✓ Plural entity type name.
Example: countries

LayoutSlot

A slot in the search result layout grid.

Properties
Property Type Required Description
slotKey string (single-slot, double-slot, triple-slot, quad-slot, small-slot-left, small-slot-right, full, left-quad, right-quad, right-quad-left-column, top-right-cell, bottom-right-cell, single-cell) ✓ Grid slot identifier.
grapherTab string (table, map, chart, line, scatter, stacked-area, discrete-bar, stacked-discrete-bar, slope, stacked-bar, marimekko) ✓ The grapher tab to display in this slot.
chartParams object Additional query params for the chart view.
previewParams object Additional query params for the preview thumbnail.

SearchDataTable

Data table for search result display.

Properties
Property Type Required Description
rows array[SearchDataTableRow] ✓
title string ✓ Title for the data table.

SearchDataTableRow

A row in the search result data table.

Properties
Property Type Required Description
seriesName string Name of the data series.
label string ✓ Display label for the row.
color string Color associated with this row.
value string Formatted value.
startValue string Formatted start value (for ranges).
time string Formatted time.
timePreposition string Preposition for time display (e.g., "in", "on").
muted boolean Whether the row should be visually muted.
striped any Whether the row should have striped styling.
outlined boolean Whether the row should have outlined styling.
rounded boolean Whether the row should have rounded corners.
trend string (up, down, unchanged) Trend direction indicator.

SearchValueDisplay

Large value display for search results.

Properties
Property Type Required Description
entityName string ✓ Name of the entity.
endValue string ✓ Formatted end value.
time string ✓ Formatted time.
unit string Unit of measurement.
startValue string Formatted start value (for ranges).
trend string (up, down, unchanged) Trend direction indicator.
showLocationIcon boolean Whether to show a location icon.
numericEndTime integer Numeric end time value.