search-charts

name	search-charts
description	Search Our World In Data's published charts by keyword to find the chart you need, across topics like population, energy and electricity, CO2 and climate, poverty and GDP, health and causes of death, education, democracy, violence and war. Use this whenever someone wants to find, browse, link or embed an OWID chart and does not already have its URL, or asks what OWID publishes on a topic. Returns each chart's title, subtitle and URL, plus which visualisations it supports so you can build a ?tab= link. Not for: fetching the data behind a URL you already have (use fetch-chart-data); Python or pandas work, indicator and column metadata, or searching the full catalog of indicators and tables beyond published charts (use owid-catalog); combining OWID data with your own (use joining-data).
allowed-tools	["Bash(curl:*)","Bash(cat:*)","Bash(jq:*)"]

Searching for charts is done via an http request to https://ourworldindata.org/api/search

Query parameters:

• q — search string (keyword-based, Algolia-powered)
• hitsPerPage — number of results per page (default: 20)
• page — page number, 0-indexed (default: 0)

The result is a json that adheres to this schema:

export enum ChartRecordType {
    Chart = "chart",
    ExplorerView = "explorerView",
    MultiDimView = "multiDimView",
}

type GrapherTabName = "LineChart" | "ScatterPlot" | "StackedArea" | "DiscreteBar" | "StackedDiscreteBar" | "SlopeChart" | "StackedBar" | "Marimekko" | "Dumbbell" | "Table" | "WorldMap"

interface BaseSearchChartHit {
    url: string
    title: string
    slug: string
    availableEntities: string[]
    originalAvailableEntities?: string[]
    variantName?: string
    subtitle?: string
    availableTabs: GrapherTabName[]
    publishedAt: string // ISO 8601 timestamp
    updatedAt: string // ISO 8601 timestamp
}

type SearchChartViewHit = BaseSearchChartHit & {
    type: ChartRecordType.Chart
}

type SearchExplorerViewHit = BaseSearchChartHit & {
    type: ChartRecordType.ExplorerView
    queryParams: string
    containerTitle: string // title of the explorer this view belongs to
}

type SearchMultiDimViewHit = BaseSearchChartHit & {
    type: ChartRecordType.MultiDimView
    queryParams: string
    containerTitle: string // title of the multi-dimensional chart this view belongs to
}

export type SearchChartHit =
    | SearchChartViewHit
    | SearchExplorerViewHit
    | SearchMultiDimViewHit

interface SearchResult {
    query: string
    results: SearchChartHit[]
    nbHits: number
    page: number
    nbPages: number
    hitsPerPage: number
}

The response json can be quite verbose, so don't pull the search results into your context window but instead use jq or a programming language to extract the information you need (often title, subtitle and url are the most relevant fields for any given hit).

Example - extract key fields from top 5 results:

curl -s "https://ourworldindata.org/api/search?q=life+expectancy&hitsPerPage=5" | jq '.results[] | {title, subtitle, url, availableTabs}'

Search Tips

The search is a keyword based search operated by Algolia. The query param q is used to submit the search string. The vocabulary used at OWID is often following that of topic specialists, so search for "death rate malaria" instead of "people who died from malaria", or "literacy" instead of "people who can read".

Results are sorted by relevance - usually the first page of hits will contain the best results. If you get a large number of charts back, and the top charts don't seem to be ideal matches, try refining the search with additional terms. If you don't get any results, try a search with slightly different terms or synonyms.

It is often a good idea to communicate the top hits back to the user and either ask them which chart/data to proceed with or to pick the best but let them know the title of a few others that were also considered.

Available Visualizations

The availableTabs field indicates what visualizations a chart supports. Use these mappings when constructing URLs:

Tab Name (from API)	URL tab parameter	Description
LineChart	line	Time series line chart
WorldMap	map	Choropleth world map
Table	table	Data table view
DiscreteBar	discrete-bar	Bar chart
SlopeChart	slope	Slope chart comparing two time points
Marimekko	marimekko	Marimekko/mosaic chart
ScatterPlot	scatter	Scatter plot
StackedArea	stacked-area	Stacked area chart
StackedBar	stacked-bar	Stacked bar chart
StackedDiscreteBar	stacked-discrete-bar	Stacked bar chart for a single time point
Dumbbell	dumbbell	Dumbbell chart comparing two values per entity

To display a specific visualization, append ?tab=<value> to the chart URL. For example:

https://ourworldindata.org/grapher/life-expectancy?tab=map

Using Search Results

To fetch the data behind a chart, use the url property as is verbatim, including all query params. Consult the fetch-chart-data skill for more details on how best to request the data and metadata.