Our World in Data

Put the world's research data into a workflow. Our World in Data collects what the UN, the World Bank, the WHO, the IHME and a few hundred other institutions publish on how the world is changing - life expectancy, emissions, poverty, energy, health, education - puts every country on the same names and the same years, and publishes one chart per question. Search those charts by subject, or describe what you need in plain English and let it find the indicator that means it. Then read the numbers: one country's latest figure for a sentence in an email, a run of years for a report, several countries ranked side by side, or the top and bottom of the world. Take a picture of any chart to put in a message, and get the line that credits its sources back with every answer, because all of it is CC BY and asks to be cited. Every action reads: nothing here changes anything. No account or API key required.

Actions

Action	What it does
Compare countries	Put several countries side by side on one chart, ranked largest first, each with its share of their combined total and how far it is behind the leader.
Find articles	Search what Our World in Data writes rather than what it charts: research articles, the short daily data insights, and the topic pages that explain a subject end to end.
Find charts	Search Our World in Data's charts and get back the name of each one, which is what every other step here is keyed on.
Find indicators	Describe what you are looking for in plain English and get back the indicators that mean it, ranked by how closely.
Get a chart image	A picture of a chart as a link you can drop straight into an email, a Slack message or a document - drawn for the countries and years you choose, as the chart or as the world map, at the size the place it is going needs.
Get a country's data over time	One or more countries' numbers from one chart across a span of time, as a row per country per year - and, alongside them, a summary of each country saying where it started, where it ended, how far it moved in the unit and in percent, and its highest, lowest and average.
Get a country's latest value	One country's most recent figure from one chart, with the year it is from, the unit it is in and the line that credits its sources - plus where the number started and how far it has moved since, so a sentence can say both.
Get chart details	Everything about one chart except the numbers: what it measures and in what unit, what Our World in Data says you should know about it, which countries and years it covers, when it was last updated and when it is due to be updated next, and the line that credits its sources.
Get indicator data	Read the numbers behind one indicator from 'Find indicators', whether or not any chart is drawn from it - which is most of them.
Rank countries	The highest or lowest countries in the world on one chart, with the global figure alongside when the chart publishes one.

Compare countries

Put several countries side by side on one chart, ranked largest first, each with its share of their combined total and how far it is behind the leader. Every country is read at its own most recent year, because statistical agencies publish on their own schedules and insisting on one shared year would silently drop whoever had not reported yet. Anything the chart does not cover is reported as missing rather than quietly left out. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
Countries to comparecountriestextRequired: Between two and twenty-five countries to compare. Countries by name ('Japan') or three-letter code ('JPN'). Capitals and punctuation do not matter. 'World' reads the global figure, and the continents and income groups Our World in Data publishes can be chosen the same way.
As ofas_ofdate: Read the numbers as they stood on this date. Leave blank for the most recent figures, which is what keeps a scheduled workflow current. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.

Outputs

as_oftext
chart_urltext
counted_bytext
countrieslist
countries_missinglist
countries_without_datalist
country_countnumber
foundtrue/false
leadertext
leader_valuenumber
measuretext
messagetext
slugtext
totalnumber
urltext

Example output

{
  "as_of": "latest available",
  "chart_url": "https://ourworldindata.org/grapher/life-expectancy",
  "counted_by": "year",
  "countries": [
    {
      "code": "JPN",
      "country": "Japan",
      "difference_from_leader": 0,
      "rank": 1,
      "share_of_total_percent": 37.25,
      "value": 84.7123,
      "year": "2023"
    },
    {
      "code": "USA",
      "country": "United States",
      "difference_from_leader": -5.6517,
      "rank": 2,
      "share_of_total_percent": 34.76,
      "value": 79.0606,
      "year": "2023"
    },
    {
      "code": "KEN",
      "country": "Kenya",
      "difference_from_leader": -21.0594,
      "rank": 3,
      "share_of_total_percent": 27.99,
      "value": 63.6529,
      "year": "2023"
    }
  ],
  "countries_missing": [],
  "countries_without_data": [],
  "country_count": 3,
  "found": true,
  "leader": "Japan",
  "leader_value": 84.7123,
  "measure": "Life expectancy",
  "slug": "life-expectancy",
  "total": 227.4258,
  "url": "https://ourworldindata.org/grapher/life-expectancy.csv"
}

Find articles

Search what Our World in Data writes rather than what it charts: research articles, the short daily data insights, and the topic pages that explain a subject end to end. Each result comes back with its title, its authors, when it was published and an excerpt. Leave the search text blank and it returns the most recent pieces, which is how a workflow that posts 'what's new from Our World in Data' to a channel is built. No account or API key required.

Inputs

Search forquerytext: What the writing should be about. Leave blank for the most recent pieces.
Kinds of pagepage_typestext: Which kinds of page to search. Leave blank for articles and data insights, which is the writing most workflows want.One or more of: article (Articles), data-insight (Data insights (short daily posts)), topic-page (Topic pages), linear-topic-page (Topic explainers), about-page (About Our World in Data).
Number of resultsmax_resultsnumber: How many pages to return.From 1 to 100. Default: 20.
Pagepagenumber: Which page of results to return, counted from 0. Leave blank for the first.From 0 to 500. Default: 0.

Outputs

article_countnumber
articleslist
foundtrue/false
pagenumber
page_typeslist
querytext
total_matchesnumber
urltext

Example output

{
  "article_count": 1,
  "articles": [
    {
      "authors": [
        "Hannah Ritchie"
      ],
      "excerpt": "We might be individual optimists about our ability to trust and reason with evidence, and support policies that protect future generations...",
      "image_url": "https://ourworldindata.org/cdn-cgi/imagedelivery/qLq-8BTgXU8yG0N6HnOy8g/e5956f18/w=512",
      "kind": "article",
      "published_at": "2024-03-25T10:48:00.000Z",
      "slug": "climate-change-support",
      "title": "More people care about climate change than you think",
      "updated_at": "2026-02-20T08:41:30.000Z",
      "url": "https://ourworldindata.org/climate-change-support"
    }
  ],
  "found": true,
  "page": 0,
  "page_types": [
    "article",
    "data-insight"
  ],
  "query": "climate change",
  "total_matches": 106,
  "url": "https://ourworldindata.org/api/search?q=climate+change&type=pages&hitsPerPage=20&page=0&pageTypes=article,data-insight"
}

Find charts

Search Our World in Data's charts and get back the name of each one, which is what every other step here is keyed on. Search by subject - 'life expectancy', 'solar power', 'child mortality' - and narrow to a topic or to the countries you need, so a chart that does not cover your country is ruled out before a workflow is built on it. This is the step to start with: it turns a question into the chart that answers it. No account or API key required.

Inputs

Search forquerytext: What the chart should be about. Leave blank to browse a topic instead.
Topictopictext: Narrow to one of Our World in Data's topics. Leave blank to search all of them.
Must cover these countriescountriestext: Only return charts that hold data for these countries, by name. Each result also says which of them it actually covers.
Must cover every one of themrequire_all_countriestrue/false: On, a chart has to hold data for every country named above. Off, holding any one of them is enough.Default: false.
Number of resultsmax_resultsnumber: How many charts to return.From 1 to 100. Default: 20.
Pagepagenumber: Which page of results to return, counted from 0. Leave blank for the first.From 0 to 500. Default: 0.

Outputs

chart_countnumber
chartslist
foundtrue/false
pagenumber
querytext
topictext
total_matchesnumber
total_pagesnumber
urltext

Example output

{
  "chart_count": 2,
  "charts": [
    {
      "countries_matched": [
        "Japan"
      ],
      "countries_missing": [],
      "country_count": 265,
      "last_updated": "2026-08-05T17:19:40.000Z",
      "published_at": "2016-05-03T21:44:14.000Z",
      "slug": "life-expectancy",
      "subtitle": "The period life expectancy at birth, in a given year.",
      "title": "Life expectancy",
      "url": "https://ourworldindata.org/grapher/life-expectancy",
      "variant": "over the long-run",
      "views": [
        "LineChart",
        "Table",
        "WorldMap"
      ]
    },
    {
      "countries_matched": [
        "Japan"
      ],
      "countries_missing": [],
      "country_count": 236,
      "last_updated": "2025-11-19T09:02:11.000Z",
      "published_at": "2018-02-22T14:12:03.000Z",
      "slug": "life-expectancy-of-women-vs-life-expectancy-of-men",
      "subtitle": "Period life expectancy at birth.",
      "title": "Life expectancy of women vs. life expectancy of men",
      "url": "https://ourworldindata.org/grapher/life-expectancy-of-women-vs-life-expectancy-of-men",
      "variant": "",
      "views": [
        "ScatterPlot",
        "Table"
      ]
    }
  ],
  "found": true,
  "page": 0,
  "query": "life expectancy",
  "topic": "",
  "total_matches": 214,
  "total_pages": 11,
  "url": "https://ourworldindata.org/api/search?q=life+expectancy&type=charts&hitsPerPage=20&page=0"
}

Find indicators

Describe what you are looking for in plain English and get back the indicators that mean it, ranked by how closely. This searches by meaning rather than by keyword, so 'how many people die from dirty air' finds the air pollution death rates without using any of those words, and it reaches every indicator Our World in Data holds rather than only the ones a chart is drawn from. Pair it with 'Get indicator data' to read the numbers. No account or API key required.

Inputs

Describe what you needquerytextRequired: In your own words. A plain question works better than keywords, because this searches by meaning.
Number of resultsmax_resultsnumber: How many indicators to return.From 1 to 50. Default: 10.
Only ones with a chartonly_chartedtrue/false: On, leave out indicators that no Our World in Data chart draws. An indicator with a chart is the better documented one, and its chart can be pictured and linked to.Default: false.

Outputs

foundtrue/false
indicator_countnumber
indicatorslist
querytext
urltext

Example output

{
  "found": true,
  "indicator_count": 2,
  "indicators": [
    {
      "catalog_path": "grapher/health/2019/deaths_attributed_to_air_pollution__lelieveld_et_al__2019",
      "chart_count": 0,
      "description": "",
      "indicator_id": 1206233,
      "match_score": 0.9431,
      "name": "Deaths from anthropogenic pollution as a share of total air pollution deaths",
      "unit": "%"
    },
    {
      "catalog_path": "grapher/health/2019/deaths_attributed_to_air_pollution__lelieveld_et_al__2019",
      "chart_count": 3,
      "description": "",
      "indicator_id": 1206238,
      "match_score": 0.939,
      "name": "Excess mortality from air pollution (all sources)",
      "unit": "deaths per year"
    }
  ],
  "query": "deaths from air pollution",
  "url": "https://search.owid.io/indicators?q=deaths+from+air+pollution&limit=10"
}

Get a chart image

A picture of a chart as a link you can drop straight into an email, a Slack message or a document - drawn for the countries and years you choose, as the chart or as the world map, at the size the place it is going needs. The link is checked before it comes back, so a step never hands on an address that will show a broken image. Our World in Data's charts are CC BY, so the credit line to put beside it comes back too. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
Countries to showcountriestext: Which countries to draw. Leave blank for the chart's own default selection. Countries by name ('Japan') or three-letter code ('JPN'). Capitals and punctuation do not matter. 'World' reads the global figure, and the continents and income groups Our World in Data publishes can be chosen the same way.
Fromstartdate: The earliest date to include. Leave blank to start at the beginning of the data. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.
Toenddate: The latest date to include. Leave blank to run to the most recent figures, which is what keeps a scheduled workflow current.
Viewviewtext: Draw the chart itself, or the world map of the same numbers.One of: chart (The chart), map (The world map). Default: chart.
Image formatimage_formattext: PNG for anywhere a picture is shown; SVG stays sharp at any size but not every email client renders it.One of: png (PNG (for email, Slack and documents)), svg (SVG (sharp at any size, for print)). Default: png.
Sizesizetext: How large to draw it, and for what.One of: standard (Standard - 850 x 600), wide (Wide - 1200 x 628, for a link preview), square (Square - 1080 x 1080, for social media). Default: standard.

Outputs

attributiontext
chart_urltext
countrieslist
formattext
foundtrue/false
fromtext
heightnumber
image_urltext: Drop this straight into an email, a message or a document.
licensetext
renamed_fromtext
sizetext
slugtext
totext
viewtext
widthnumber

Example output

{
  "attribution": "Our World in Data. https://ourworldindata.org/grapher/life-expectancy",
  "chart_url": "https://ourworldindata.org/grapher/life-expectancy",
  "countries": [
    "Japan",
    "Kenya"
  ],
  "format": "png",
  "found": true,
  "from": "2000-01-01",
  "height": 600,
  "image_url": "https://ourworldindata.org/grapher/life-expectancy.png?country=Japan~Kenya&time=2000..2023&imWidth=850&imHeight=600",
  "license": "CC BY 4.0",
  "size": "standard",
  "slug": "life-expectancy",
  "to": "2023-12-31",
  "view": "chart",
  "width": 850
}

Get a country's data over time

One or more countries' numbers from one chart across a span of time, as a row per country per year - and, alongside them, a summary of each country saying where it started, where it ended, how far it moved in the unit and in percent, and its highest, lowest and average. That summary is usually the answer: it is what turns a table of numbers into a sentence a report can use. Leave the dates blank for everything the chart holds. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
CountriescountriestextRequired: Countries by name ('Japan') or three-letter code ('JPN'). Capitals and punctuation do not matter. 'World' reads the global figure, and the continents and income groups Our World in Data publishes can be chosen the same way.
Fromstartdate: The earliest date to include. Leave blank to start at the beginning of the data. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.
Toenddate: The latest date to include. Leave blank to run to the most recent figures, which is what keeps a scheduled workflow current.
Maximum rowsmax_rowsnumber: How many rows to return at most. A row is one country in one year, so two centuries of five countries is a thousand of them.From 1 to 5000. Default: 500.

Outputs

chart_urltext
counted_bytext: 'year' for almost every chart, 'day' for the daily ones.
countrieslist
countries_missinglist
foundtrue/false
fromtext
measuretext
row_countnumber
rowslist
serieslist: One summary per country: where it started, ended and moved.
slugtext
totext
total_rowsnumber
truncatedtrue/false
urltext

Example output

{
  "chart_url": "https://ourworldindata.org/grapher/life-expectancy",
  "counted_by": "year",
  "countries": [
    "Japan",
    "Kenya"
  ],
  "countries_missing": [],
  "found": true,
  "from": "2000-01-01",
  "measure": "Life expectancy",
  "row_count": 4,
  "rows": [
    {
      "code": "JPN",
      "country": "Japan",
      "value": 81.1788,
      "year": "2000"
    },
    {
      "code": "JPN",
      "country": "Japan",
      "value": 84.7123,
      "year": "2023"
    },
    {
      "code": "KEN",
      "country": "Kenya",
      "value": 51.6802,
      "year": "2000"
    },
    {
      "code": "KEN",
      "country": "Kenya",
      "value": 63.6529,
      "year": "2023"
    }
  ],
  "series": [
    {
      "average": 83.29,
      "change": 3.5335,
      "change_percent": 4.35,
      "country": "Japan",
      "first_value": 81.1788,
      "first_year": "2000",
      "highest": 84.7123,
      "latest_value": 84.7123,
      "latest_year": "2023",
      "lowest": 81.1788,
      "points": 24
    },
    {
      "average": 58.11,
      "change": 11.9727,
      "change_percent": 23.17,
      "country": "Kenya",
      "first_value": 51.6802,
      "first_year": "2000",
      "highest": 63.6529,
      "latest_value": 63.6529,
      "latest_year": "2023",
      "lowest": 50.9134,
      "points": 24
    }
  ],
  "slug": "life-expectancy",
  "to": "2023-12-31",
  "total_rows": 4,
  "truncated": false,
  "url": "https://ourworldindata.org/grapher/life-expectancy.csv"
}

Get a country's latest value

One country's most recent figure from one chart, with the year it is from, the unit it is in and the line that credits its sources - plus where the number started and how far it has moved since, so a sentence can say both. This is the step for putting a real number into an email, a message or a document. Leave the date blank and it stays current on its own as the statistical agencies publish. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
CountrycountrytextRequired: Countries by name ('Japan') or three-letter code ('JPN'). Capitals and punctuation do not matter. 'World' reads the global figure, and the continents and income groups Our World in Data publishes can be chosen the same way.
As ofas_ofdate: Read the numbers as they stood on this date. Leave blank for the most recent figures, which is what keeps a scheduled workflow current. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.

Outputs

as_oftext
change_percent_since_firstnumber
change_since_firstnumber
counted_bytext: 'year' for almost every chart, 'day' for the daily ones.
countrytext
daytext
first_daytext
first_valuenumber
first_yearnumber
formatted_valuetext: The number as Our World in Data itself prints it.
foundtrue/false
messagetext
nametext
renamed_fromtext
slugtext
sourceobject: Who collected the numbers, and the line that credits them.
unittext
urltext
valuenumber
yearnumber

Example output

{
  "as_of": "latest available",
  "change_percent_since_first": 132.56,
  "change_since_first": 48.2863,
  "counted_by": "year",
  "country": "Japan",
  "first_value": 36.426,
  "first_year": 1865,
  "formatted_value": "84.7 years",
  "found": true,
  "name": "Life expectancy",
  "slug": "life-expectancy",
  "source": {
    "attribution": "UN WPP (2024); HMD (2025); Zijdeman et al. (2015); Riley (2005) - with major processing by Our World in Data. https://ourworldindata.org/grapher/life-expectancy",
    "citation": "UN WPP (2024); HMD (2025); Zijdeman et al. (2015); Riley (2005)",
    "license": "CC BY 4.0",
    "url": "https://ourworldindata.org/grapher/life-expectancy"
  },
  "unit": "years",
  "url": "https://ourworldindata.org/grapher/life-expectancy",
  "value": 84.7123,
  "year": 2023
}

Get chart details

Everything about one chart except the numbers: what it measures and in what unit, what Our World in Data says you should know about it, which countries and years it covers, when it was last updated and when it is due to be updated next, and the line that credits its sources. Read this before building on a chart, so a workflow is written against what it actually holds, and read it alongside the numbers so a report cites them properly. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
List the countries it coversinclude_countriestrue/false: On, the answer lists every country and region in the chart. Turn it off for a shorter answer when you only need the description and the citation.Default: true.

Outputs

counted_bytext: 'year' for almost every chart, 'day' for the daily ones.
countrieslist
country_countnumber
data_downloadedtext
first_yeartext
foundtrue/false
latest_yeartext
renamed_fromtext
serieslist
series_countnumber
shown_by_defaultlist
slugtext
sourceobject: Who collected the numbers, and the line that credits them.
subtitletext
titletext
unittext
urltext

Example output

{
  "counted_by": "year",
  "countries": [
    "Afghanistan",
    "Africa",
    "Albania",
    "Algeria"
  ],
  "country_count": 265,
  "data_downloaded": "2026-09-12",
  "first_year": "1543",
  "found": true,
  "latest_year": "2023",
  "series": [
    {
      "citation": "UN WPP (2024); HMD (2025) - with minor processing by Our World in Data",
      "column": "Period life expectancy at birth",
      "description": "Period life expectancy is the number of years the average person born in a certain year would live.",
      "full_name": "Life expectancy at birth - Various sources",
      "indicator_id": 1118466,
      "key_points": [
        "In 1900, the global average life expectancy was 32 years. By 2023, this had more than doubled to 73 years."
      ],
      "last_updated": "2025-10-22",
      "name": "Life expectancy",
      "next_update": "2026-11-30",
      "short_unit": "years",
      "timespan": "1543-2023",
      "unit": "years"
    }
  ],
  "series_count": 1,
  "shown_by_default": [
    "World",
    "Americas",
    "Europe",
    "Africa"
  ],
  "slug": "life-expectancy",
  "source": {
    "attribution": "UN WPP (2024); HMD (2025); Zijdeman et al. (2015); Riley (2005) - with major processing by Our World in Data. https://ourworldindata.org/grapher/life-expectancy",
    "citation": "UN WPP (2024); HMD (2025); Zijdeman et al. (2015); Riley (2005)",
    "license": "CC BY 4.0",
    "url": "https://ourworldindata.org/grapher/life-expectancy"
  },
  "subtitle": "The period life expectancy at birth, in a given year.",
  "title": "Life expectancy",
  "unit": "years",
  "url": "https://ourworldindata.org/grapher/life-expectancy"
}

Get indicator data

Read the numbers behind one indicator from 'Find indicators', whether or not any chart is drawn from it - which is most of them. The values arrive keyed by internal entity number; this step turns them back into country names, narrows them to the countries and years you asked for, and returns the indicator's unit, its dataset and the organisations that collected it. No account or API key required.

Inputs

IndicatorindicatornumberRequired: The indicator's number, as 'Find indicators' reports it for each result.
Countriescountriestext: Narrow to these countries. Leave blank for every country the indicator covers. Countries by name ('Japan') or three-letter code ('JPN'). Capitals and punctuation do not matter. 'World' reads the global figure, and the continents and income groups Our World in Data publishes can be chosen the same way.
Fromstartdate: The earliest date to include. Leave blank to start at the beginning of the data. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.
Toenddate: The latest date to include. Leave blank to run to the most recent figures, which is what keeps a scheduled workflow current.
Maximum rowsmax_rowsnumber: How many rows to return at most. A row is one country in one year, so two centuries of five countries is a thousand of them.From 1 to 5000. Default: 500.

Outputs

countrieslist
countries_missinglist
datasettext
descriptiontext
foundtrue/false
indicator_idnumber
last_updatedtext
nametext
row_countnumber
rowslist
sourceobject
timespantext
total_rowsnumber
truncatedtrue/false
unittext
urltext

Example output

{
  "countries": [
    "Japan"
  ],
  "countries_missing": [],
  "dataset": "Life Expectancy (period)",
  "description": "Period life expectancy is the number of years the average person born in a certain year would live.",
  "found": true,
  "indicator_id": 1118466,
  "last_updated": "2025-10-22T14:58:55.000Z",
  "name": "Life expectancy",
  "row_count": 2,
  "rows": [
    {
      "code": "JPN",
      "country": "Japan",
      "value": 84.0446,
      "year": 2022
    },
    {
      "code": "JPN",
      "country": "Japan",
      "value": 84.7123,
      "year": 2023
    }
  ],
  "source": {
    "attribution": "Human Mortality Database; United Nations - with major processing by Our World in Data. https://api.ourworldindata.org/v1/indicators/1118466.metadata.json",
    "citation": "Human Mortality Database; United Nations",
    "license": "CC BY 4.0",
    "processing_level": "major",
    "producers": [
      "Human Mortality Database",
      "United Nations"
    ],
    "url": "https://api.ourworldindata.org/v1/indicators/1118466.metadata.json"
  },
  "timespan": "1543-2023",
  "total_rows": 2,
  "truncated": false,
  "unit": "years",
  "url": "https://api.ourworldindata.org/v1/indicators/1118466.data.json"
}

Rank countries

The highest or lowest countries in the world on one chart, with the global figure alongside when the chart publishes one. Continents, income groups and the world itself are left out by default - they are much larger than any country, so a ranking that kept them would be a ranking of continents - but they can be put back in. Each country is read at its own most recent year. No account or API key required.

Inputs

ChartslugtextRequired: The Our World in Data chart to read. Paste the whole address of the chart page - https://ourworldindata.org/grapher/life-expectancy - or just the last part of it. Use 'Find charts' to look one up.
Which endordertext: Whether to take the top of the ranking or the bottom.One of: highest (Highest first), lowest (Lowest first). Default: highest.
How manycountnumber: How many countries to return.From 1 to 100. Default: 10.
As ofas_ofdate: Read the numbers as they stood on this date. Leave blank for the most recent figures, which is what keeps a scheduled workflow current. Most Our World in Data charts are counted in years, so only the year is used; the daily charts use the whole date.
Include continents and income groupsinclude_regionstrue/false: On, Our World in Data's aggregates - continents, income groups, the world - are ranked alongside the countries. They are usually much larger, so leaving this off is what keeps a ranking a ranking of countries.Default: false.

Outputs

as_oftext
chart_urltext
counted_bytext
countrieslist
foundtrue/false
includes_regionstrue/false
leadertext
leader_valuenumber
measuretext
messagetext
ordertext
ranked_out_ofnumber
slugtext
urltext
worldobject: The global figure, when the chart publishes one.

Example output

{
  "as_of": "latest available",
  "chart_url": "https://ourworldindata.org/grapher/life-expectancy",
  "counted_by": "year",
  "countries": [
    {
      "code": "MCO",
      "country": "Monaco",
      "rank": 1,
      "value": 86.5,
      "year": "2023"
    },
    {
      "code": "HKG",
      "country": "Hong Kong",
      "rank": 2,
      "value": 85.51,
      "year": "2023"
    },
    {
      "code": "JPN",
      "country": "Japan",
      "rank": 3,
      "value": 84.71,
      "year": "2023"
    }
  ],
  "found": true,
  "includes_regions": false,
  "leader": "Monaco",
  "leader_value": 86.5,
  "measure": "Life expectancy",
  "order": "highest",
  "ranked_out_of": 237,
  "slug": "life-expectancy",
  "url": "https://ourworldindata.org/grapher/life-expectancy.csv",
  "world": {
    "value": 73.17,
    "year": "2023"
  }
}

ActionsCopy Anchor Link

Compare countriesCopy Anchor Link

Inputs

Outputs

Find articlesCopy Anchor Link

Inputs

Outputs

Find chartsCopy Anchor Link

Inputs

Outputs

Find indicatorsCopy Anchor Link

Inputs

Outputs

Get a chart imageCopy Anchor Link

Inputs

Outputs

Get a country's data over timeCopy Anchor Link

Inputs

Outputs

Get a country's latest valueCopy Anchor Link

Inputs

Outputs

Get chart detailsCopy Anchor Link

Inputs

Outputs

Get indicator dataCopy Anchor Link

Inputs

Outputs

Rank countriesCopy Anchor Link

Inputs

Outputs

On this page

Actions

Compare countries

Find articles

Find charts

Find indicators

Get a chart image

Get a country's data over time

Get a country's latest value

Get chart details

Get indicator data

Rank countries