# Our World in Data API

> Our World in Data returns country-by-year statistics as a workflow and API.

Our World in Data (OWID) returns numeric country-by-year values from the best-matching chart for a named statistic. Get statistic returns chart details, definitions, sources, units, and values; provide a statistic and optionally countries and years.

- Page: https://fous.com/tools/our-world-in-data
- Handle: `@our-world-in-data`
- Category: [Data](https://fous.com/tools/category/data)
- Source website: https://ourworldindata.org
- Last verified: Sep 29, 2026

## Methods

### Get statistic

Operation `get_statistic`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a country-by-year statistic from the best-matching Our World in Data chart. Returns the selected chart, its definition and source, and numeric values. Only charts with downloadable numeric time-series data are supported.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `to_year` | integer | no | `2022` | Last year to include. Example: 2020. Defaults to the latest available year. |
| `countries` | string | no | `"World, United States"` | Country names separated by commas. Example: France, Germany. Defaults to World. |
| `from_year` | integer | no | `2020` | First year to include. Example: 2000. Defaults to the earliest available year. |
| `statistic` | string | yes | `"CO2 emissions"` | The statistic to measure, in plain words. Example: life expectancy. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "statistic"
  ],
  "properties": {
    "to_year": {
      "type": "integer",
      "description": "Last year to include. Example: 2020. Defaults to the latest available year.",
      "examples": [
        2022,
        2020,
        2021
      ]
    },
    "countries": {
      "type": "string",
      "default": "World",
      "description": "Country names separated by commas. Example: France, Germany. Defaults to World.",
      "examples": [
        "World, United States",
        "France, Germany",
        "World"
      ]
    },
    "from_year": {
      "type": "integer",
      "description": "First year to include. Example: 2000. Defaults to the earliest available year.",
      "examples": [
        2020,
        2018
      ]
    },
    "statistic": {
      "type": "string",
      "description": "The statistic to measure, in plain words. Example: life expectancy.",
      "examples": [
        "CO2 emissions",
        "life expectancy",
        "GDP per person"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "to_year": 2022,
      "countries": "World, United States",
      "from_year": 2020,
      "statistic": "CO2 emissions"
    },
    {
      "to_year": 2020,
      "countries": "France, Germany",
      "from_year": 2018,
      "statistic": "life expectancy"
    },
    {
      "to_year": 2021,
      "countries": "World",
      "from_year": 2020,
      "statistic": "GDP per person"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `unit` | string or null | `"tonnes"` | Measurement unit. |
| `source` | string or null | `"Global Carbon Budget (2025) – with major processing by Our World in Data"` | Original data source citation. |
| `values` | array |  | Numeric observations sorted by country and then year. |
| `values[].year` | integer | `2020` |  |
| `values[].value` | number | `4689954000` |  |
| `values[].country` | string | `"United States"` |  |
| `chart_link` | string | `"https://ourworldindata.org/grapher/annual-co2-emissions-per-country"` | Link to the selected chart. |
| `definition` | string or null | `"Annual total emissions of carbon dioxide (CO₂), excluding land-use change, measured in tonnes."` | What the statistic measures. |
| `chart_title` | string | `"Annual CO₂ emissions"` | Title of the chart used. |

**Example input**

```json
{
  "to_year": 2022,
  "countries": "World, United States",
  "from_year": 2020,
  "statistic": "CO2 emissions"
}
```

**Example output**

```json
{
  "unit": "tonnes",
  "source": "Global Carbon Budget (2025) – with major processing by Our World in Data",
  "values": [
    {
      "year": 2020,
      "value": 4689954000,
      "country": "United States"
    },
    {
      "year": 2021,
      "value": 5020111000,
      "country": "United States"
    },
    {
      "year": 2022,
      "value": 5055403000,
      "country": "United States"
    }
  ],
  "chart_link": "https://ourworldindata.org/grapher/annual-co2-emissions-per-country",
  "definition": "Annual total emissions of carbon dioxide (CO₂), excluding land-use change, measured in tonnes.",
  "chart_title": "Annual CO₂ emissions"
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@our-world-in-data",
  "visibility": "public",
  "operation": "get_statistic",
  "version": 1,
  "input": {
    "to_year": 2022,
    "countries": "World, United States",
    "from_year": 2020,
    "statistic": "CO2 emissions"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@our-world-in-data\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_statistic\",\n  \"version\": 1,\n  \"input\": {\n    \"to_year\": 2022,\n    \"countries\": \"World, United States\",\n    \"from_year\": 2020,\n    \"statistic\": \"CO2 emissions\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@our-world-in-data",
  "visibility": "public",
  "operation": "get_statistic",
  "version": 1,
  "input": {
    "to_year": 2022,
    "countries": "World, United States",
    "from_year": 2020,
    "statistic": "CO2 emissions"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/our-world-in-data`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_statistic`: Get statistic. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-our-world-in-data https://api.fous.com/mcp/tools/our-world-in-data --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare a statistic across countries and years
- Track changes in a statistic over time
- Find the source and definition for a statistic
- Build country-level reports from historical values

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Our World in Data tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Our World in Data account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from ourworldindata.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What was life expectancy in France in 2020?

Use Get statistic with life expectancy, France, and 2020 as the first and last years.

### How did a statistic change over time?

Use Get statistic with the statistic and the desired first and last years.

### Which source and definition support a statistic?

Get statistic returns the selected chart’s source and definition.

## Related

- [World Bank API](https://fous.com/tools/world-bank.md): World Bank provides country statistics and latest values within selected years, plus country rankings for a chosen year or the latest broadly covered year.
- [World Health Organization API](https://fous.com/tools/world-health-organization.md): The World Health Organization provides public health information, latest outbreak reports, country health statistics with up to 10 years of history when available, and topic fact sheets.
- [Eurostat API](https://fous.com/tools/eurostat.md): Official European statistics from Eurostat.
- [IMF API](https://fous.com/tools/imf.md): IMF economic data provides country and regional forecasts with actual or forecast labels, and country rankings by World Economic Outlook indicators, excluding groups and missing values.
- [Kworb API](https://fous.com/tools/kworb.md): Kworb provides published Spotify and YouTube music charts and tracked artist streaming totals; chart dates may lag, and daily streams or some views may be unavailable.
- [Wikipedia API](https://fous.com/tools/wikipedia.md): Wikipedia returns article summaries, images, facts, relevant search matches, readable text and daily historical events, plus human-view counts from July 2015 onward.
- [Trading Economics API](https://fous.com/tools/trading-economics.md): Trading Economics provides economic indicators, market data and country statistics, including country overviews, latest reported country comparisons and current commodity prices reflecting reported trading days.
- [Deezer API](https://fous.com/tools/deezer.md): Deezer provides albums with ordered tracklists, song recording details, and current worldwide charts or official country-playlist tracks; previews and some tempo data may be unavailable or expire.
- [All Data tools](https://fous.com/tools/category/data)