Search API¶

Search API for accessing Our World in Data charts and content pages powered by Algolia.

This API allows you to search through:

Charts: Interactive data visualizations with country-specific filtering
Pages: Articles, research papers, and informational pages

Semantic Search

We also offer semantic search for indicators via the Semantic Search API. This allows natural language queries like "deaths from air pollution" to find relevant indicators.

API Information

Version: 0.1.0

Base URL: https://ourworldindata.org/api — Site API

License: CC BY 4.0

GET `/search`¶

Search for charts or pages

Search through Our World in Data's collection of charts and pages.

For chart search: Filter by countries, topics, and entity availability
For page search: Find articles, research papers, and informational content

Parameters¶

Parameter	Type	Description
`q`	string	Search query text default: `""` Example: `population`
`type`	string (`charts`, `pages`)	Type of content to search default: `charts` Example: `charts`
`page`	integer	Page number for pagination (0-indexed) default: `0`
`hitsPerPage`	integer	Number of results per page default: `20`
`countries`	string	Country names separated by `~` (tilde). Only applicable when `type=charts`. Example: `United States~China`
`topics`	string	Topic name for filtering charts. Only applicable when `type=charts`. View all available topics Example: `Health`
`requireAllCountries`	boolean	If `true`, only return charts that include ALL specified countries. Only applicable when `type=charts` and `countries` parameter is provided. default: `False` Example: `False`

Responses¶

✅ 200 - Successful search response

Content-Type: application/json

Chart searchPage search

Request: GET https://ourworldindata.org/api/search?q=gdp

Code samples:

cURLPythonJavaScriptRust

curl "https://ourworldindata.org/api/search?q=gdp"

import requests

params = {
    "q": "gdp"
}
response = requests.get("https://ourworldindata.org/api/search", params=params)
data = response.json()

const params = new URLSearchParams({ q: "gdp" });
const response = await fetch(`https://ourworldindata.org/api/search?${params}`);
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/api/search")
        .query(&[("q", "gdp")])
    .await?
    .json::<serde_json::Value>()
    .await?;

{
  "query": "gdp",
  "results": [
    {
      "title": "GDP per capita",
      "slug": "gdp-per-capita-worldbank",
      "subtitle": "GDP per capita is a country's gross domestic product divided by its population. This data is adjusted for inflation and differences in living costs between countries.",
      "variantName": "World Bank, constant international-$",
      "type": "chart",
      "availableEntities": [
        "United States",
        "China",
        "India"
      ],
      "originalAvailableEntities": [
        "Bosnia and Herzegovina",
        "United States",
        "China",
        "India"
      ],
      "availableTabs": [
        "LineChart",
        "Table",
        "WorldMap"
      ],
      "publishedAt": "2016-05-03T21:44:14.000Z",
      "updatedAt": "2025-12-20T15:23:24.000Z",
      "url": "https://ourworldindata.org/grapher/gdp-per-capita-worldbank"
    }
  ],
  "nbHits": 360,
  "page": 0,
  "nbPages": 18,
  "hitsPerPage": 20
}

Request: GET https://ourworldindata.org/api/search?q=climate+change&type=pages

Code samples:

cURLPythonJavaScriptRust

curl "https://ourworldindata.org/api/search?q=climate+change&type=pages"

import requests

params = {
    "q": "climate change",
    "type": "pages"
}
response = requests.get("https://ourworldindata.org/api/search", params=params)
data = response.json()

const params = new URLSearchParams({ q: "climate change", type: "pages" });
const response = await fetch(`https://ourworldindata.org/api/search?${params}`);
const data = await response.json();

let response = reqwest::get("https://ourworldindata.org/api/search")
        .query(&[("q", "climate change")])
        .query(&[("type", "pages")])
    .await?
    .json::<serde_json::Value>()
    .await?;

{
  "query": "climate change",
  "results": [
    {
      "type": "article",
      "slug": "climate-change-support",
      "title": "More people care about climate change than you think",
      "content": "You’ll get more clicks by making people angry at others for disagreeing. “Both sides” debates, for example in talk shows, can also give people the impression that they accurately reflect balance among the public. People think that far more people are opposed to climate action as a result.The debate is now about the merits of different solutions, not whether we should actFor decades, the world debated whether climate change was happening, if humans were causing it, and if we should do something. If you look at levels of concern in the UK since the millennium, for example, you find an interesting decline-then-rise. In the first decade of the 2000s, environmental concerns were very high. In 2005/06, 82% of Brits said they were concerned about “global warming”. This was around the time that Al Gore’s film An Inconvenient Truth was released. The Stern Report on the impacts and economics of climate change was published. And not far ahead of the release of the UK’s Climate Change Act.",
      "date": "2024-03-25T10:48:30.000Z",
      "modifiedDate": "2024-03-25T10:48:41.000Z",
      "thumbnailUrl": "https://ourworldindata.org/cdn-cgi/imagedelivery/qLq-8BTgXU8yG0N6HnOy8g/e5956f18-560f-4639-ad7e-c18553856600/w=512",
      "authors": [
        "Hannah Ritchie"
      ],
      "url": "https://ourworldindata.org/climate-change-support"
    }
  ],
  "nbHits": 104,
  "offset": 0,
  "length": 20
}

❌ 400 - Bad request - invalid parameters

Content-Type: application/json

Example:

{
  "error": "Invalid parameter value",
  "message": "hitsPerPage must be between 1 and 100"
}

❌ 500 - Internal server error

Content-Type: application/json

Example:

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Schemas¶

`ChartSearchResponse`¶

Response object for chart search queries, containing search results and pagination metadata.

Properties

Property	Type	Required	Description
`query`	string	✓	The search query that was executed Example: `population`
`results`	array[ChartResult]	✓	Array of chart search results
`nbHits`	integer	✓	Total number of results found Example: `125`
`page`	integer	✓	Current page number (0-indexed) Example: `0`
`nbPages`	integer	✓	Total number of pages available Example: `7`
`hitsPerPage`	integer	✓	Number of results per page Example: `20`

`ChartResult`¶

Individual chart search result with metadata about the visualization.

Properties

Property	Type	Required	Description
`title`	string	✓	Chart title Example: `Life expectancy at birth`
`slug`	string	✓	URL-friendly identifier for the chart Example: `life-expectancy`
`subtitle`	string		Chart subtitle providing additional context Example: `Period life expectancy at birth, measured in years`
`variantName`	string		Name of the chart variant (if applicable) Example: `Default`
`type`	string (`chart`, `explorerView`, `multiDimView`)	✓	Type of visualization Example: `chart`
`queryParams`	string		URL query parameters for explorer or multi-dimensional views Example: `tab=chart&time=2020`
`availableEntities`	`array[string]`	✓	List of countries/entities available in this chart Example: `United States`, `China`, `India`
`originalAvailableEntities`	`array[string]`		Original list of entities before filtering Example: `United States`, `United Kingdom`
`availableTabs`	`array[string (`Table`,`WorldMap`,`LineChart`,`ScatterPlot`,`StackedArea`,`DiscreteBar`,`StackedDiscreteBar`,`SlopeChart`,`StackedBar`,`Marimekko`)]`	✓	Available visualization tabs Example: `Table`, `WorldMap`, `LineChart`, ...
`publishedAt`	string (date-time)		Publication date of the chart (ISO 8601 format) Example: `2016-05-03T21:44:14.000Z`
`updatedAt`	string (date-time)		Last update date of the chart (ISO 8601 format) Example: `2025-12-20T15:23:24.000Z`
`url`	string (uri)	✓	Full URL to access the chart Example: `https://ourworldindata.org/grapher/life-expectancy`

`PageSearchResponse`¶

Response object for page/article search queries, containing search results and pagination metadata.

Properties

Property	Type	Required	Description
`query`	string	✓	The search query that was executed Example: `climate change`
`results`	array[PageResult]	✓	Array of page search results
`nbHits`	integer	✓	Total number of results found Example: `42`
`offset`	integer	✓	Current offset in the result set Example: `0`
`length`	integer	✓	Number of results returned Example: `20`

`PageResult`¶

Individual page/article search result with metadata about the content.

Properties

Property	Type	Required	Description
`title`	string	✓	Page title Example: `CO₂ emissions`
`slug`	string	✓	URL-friendly identifier for the page Example: `co2-emissions`
`type`	string (`article`, `about-page`)	✓	Type of page content Example: `article`
`thumbnailUrl`	string (uri)		URL to page thumbnail image Example: `https://ourworldindata.org/images/co2-thumbnail.jpg`
`date`	string (date-time)		Publication of the article (ISO 8601 format) Example: `2024-09-30T08:57:00.000Z`
`modifiedDate`	string (date-time)		Last update date (ISO 8601 format) Example: `2025-08-21T15:57:34.000Z`
`content`	string		Excerpt or snippet of page content Example: `Carbon dioxide emissions are the primary driver of global climate change...`
`authors`	`array[string]`		List of page authors Example: `Hannah Ritchie`, `Max Roser`
`url`	string (uri)	✓	Full URL to access the page Example: `https://ourworldindata.org/co2-emissions`

`Error`¶

Error response object returned when a request fails.

Properties

Property	Type	Required	Description
`error`	string	✓	Error type or category Example: `Invalid parameter`
`message`	string		Detailed error message Example: `The 'page' parameter must be between 0 and 1000`

Search API¶

GET /search¶

Parameters¶

Responses¶

Schemas¶

ChartSearchResponse¶

ChartResult¶

PageSearchResponse¶

PageResult¶

Error¶

GET `/search`¶

`ChartSearchResponse`¶

`ChartResult`¶

`PageSearchResponse`¶

`PageResult`¶

`Error`¶