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:

https://ourworldindata.org/grapher/life-expectancy - the page on our website where you can see the chart
https://ourworldindata.org/grapher/life-expectancy.csv - the data for this chart
https://ourworldindata.org/grapher/life-expectancy.metadata.json - the metadata for this chart, like the chart title, the units, how to cite the data sources
https://ourworldindata.org/grapher/life-expectancy.zip - the above two plus a readme as zip file archive

Example notebooks

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

Example python notebook on Google Colab using Pandas
ObservableHQ notebook using Javascript to recreate the life expectancy chart

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

Life expectancy - full dataLife expectancy - filtered by country and time

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

Code samples:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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:

cURLPythonJavaScriptRust

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	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	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	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	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.

Grapher Chart API¶

GET /grapher/{slug}¶

Parameters¶

Responses¶

GET /grapher/{slug}.{format}¶

Parameters¶

Responses¶

GET /grapher/{slug}.csv¶

Parameters¶

Responses¶

GET /grapher/{slug}.metadata.json¶

Parameters¶

Responses¶

GET /grapher/{slug}.readme.md¶

Parameters¶

Responses¶

GET /grapher/{slug}.zip¶

Parameters¶

Responses¶

GET /grapher/{slug}.config.json¶

Parameters¶

Responses¶

GET /grapher/{slug}.values.json¶

Parameters¶

Responses¶

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

Parameters¶

Responses¶

Schemas¶

Error¶

ChartMetadata¶

ChartMetadataChart¶

ChartMetadataColumn¶

GrapherValuesJson¶

GrapherValuesJsonColumn¶

GrapherValuesJsonDataPoints¶

GrapherValuesJsonDataPoint¶

GrapherSearchResultJson¶

LayoutSlot¶

SearchDataTable¶

SearchDataTableRow¶

SearchValueDisplay¶

GET `/grapher/{slug}`¶

GET `/grapher/{slug}.{format}`¶

GET `/grapher/{slug}.csv`¶

GET `/grapher/{slug}.metadata.json`¶

GET `/grapher/{slug}.readme.md`¶

GET `/grapher/{slug}.zip`¶

GET `/grapher/{slug}.config.json`¶

GET `/grapher/{slug}.values.json`¶

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

`Error`¶

`ChartMetadata`¶

`ChartMetadataChart`¶

`ChartMetadataColumn`¶

`GrapherValuesJson`¶

`GrapherValuesJsonColumn`¶

`GrapherValuesJsonDataPoints`¶

`GrapherValuesJsonDataPoint`¶

`GrapherSearchResultJson`¶

`LayoutSlot`¶

`SearchDataTable`¶

`SearchDataTableRow`¶

`SearchValueDisplay`¶