Top N emitters ranked by a metric for a given year
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.
Query parameters
Metric column name from the codebook. See /api/v1/environment/co2/codebook for the full list.
Metric column name from the codebook. See /api/v1/environment/co2/codebook for the full list.
Year to rank by. Must be within the bundle year range (1750-present).
Year to rank by. Must be within the bundle year range (1750-present).
Maximum rows to return (1 to 50).
Maximum rows to return (1 to 50).
When true, OWID aggregate entities (regions, income groups, sectoral aggregates) compete alongside ISO-coded countries.
When true, OWID aggregate entities (regions, income groups, sectoral aggregates) compete alongside ISO-coded countries.
Response
Ranked entities with their metric value, plus unit and attribution.
Example response
{
"data": {
"metric": "co2",
"unit": "million tonnes",
"year": 2022,
"limit": 20,
"ranking": [
{
"rank": 1,
"country": "China",
"iso_code": "CHN",
"value": 11902.516
}
],
"count": 20
},
"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": "sugra_crypto",
"attribution": "Short interest and Reg SHO daily short volume data is owned by and sourced from FINRA (Financial Industry Regulatory Authority).",
"fallback_chain": [
"sugra_crypto",
"sugra_finance"
]
}
}