# Search Charts

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

- Skill: `owid/search-charts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add owid/search-charts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/owid/search-charts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: owid (https://skillmd.com/u/owid)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/owid/search-charts

---


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:
```typescript
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:
```bash
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.