Top N emitters ranked by a metric for a given year

GET

/api/v1/environment/co2/top

Last modified:2026-05-10 09:22:39

Maintainer:Not configured

OperationId:environment_co2_top

Ranks entities by a metric column in descending order for one year. Answers the who emits most family of questions without requiring the caller to pull and sort the full panel. By default, only sovereign countries compete (ISO-coded rows); pass include_aggregates=true to also surface OWID aggregate entities (regions, income groups). The metric must be a column name from the codebook. Popular picks: co2, co2_per_capita, cumulative_co2, methane, temperature_change_from_co2. Published under CC BY 4.0 with dual attribution to Our World in Data and the primary upstream providers.

Request

Authorization

API Key

Add parameter in header

x-api-key

Example:

x-api-key: ********************

Query Params

Header Params

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location '/api/v1/environment/co2/top?metric=co2&year=2022&limit=20&include_aggregates=false' \
--header 'x-api-key: <api-key>'

Responses

🟢200

application/json

Ranked entities with their metric value, plus unit and attribution.

Bodyapplication/json

Example

{
    "data": {
        "metric": "co2",
        "unit": "string",
        "description": "string",
        "upstream_source": "string",
        "year": 2022,
        "limit": 20,
        "include_aggregates": false,
        "ranking": [
            {
                "rank": 1,
                "country": "China",
                "iso_code": "string",
                "value": 0
            }
        ],
        "count": 20,
        "attribution": "string"
    },
    "meta": {
        "endpoint": "/api/v1/fred/us/cpi",
        "data_time": "2026-04-16T14:30:00Z",
        "response_time": "2026-04-16T14:30:12Z",
        "provider": "Sugra API v1.0.1",
        "source": "string",
        "fallback_used": true,
        "fallback_chain": [
            "string"
        ],
        "cached": true
    }
}

🟠401

🟠422

🟠429

🔴503

Modified at 2026-05-10 09:22:39

World aggregate greenhouse-gas time series

Full column dictionary for the OWID CO2 bundle