---
title: "Catalog of entities, year range, metrics, and regions"
method: GET
path: "/api/v1/environment/co2/catalog"
tags: ["Environment"]
---

# Catalog of entities, year range, metrics, and regions

`GET /api/v1/environment/co2/catalog`

Discovery endpoint for the Our World in Data CO2 and Greenhouse Gas Emissions bundle. Lists every entity in the dataset (254 on the December 2025 vintage), the year range covered, every metric column name, and the whitelist of region aggregates accepted by `/region/{region}`. Use this before calling `/country/{iso3}`, `/country/{iso3}/{metric}`, or `/top` to confirm the exact metric spelling and the ISO codes for the countries of interest. Published under CC BY 4.0 - dual attribution to Our World in Data and the primary upstream providers named in the codebook (Global Carbon Project, Jones et al., EIA, Energy Institute, Maddison Project, OWID Population).

## Response `200`

Catalog payload with entity list, year range, metric list, and region whitelist.

- EnvelopeCo2CatalogPayload
  - `data` Co2CatalogPayload, required — Catalog of entities, year range, metrics, and region list.
    - `entities` Co2CatalogEntity[], required — List of every entity present in the bundle (254 total on the December 2025 vintage). Sort order: ISO-coded countries first, then regional aggregates.
      - `country` string, required — Entity name as published by OWID. For ISO-coded rows this is a country name (`United States`); for aggregates this is a regional label (`World`, `Africa`, `European Union (27)`).
      - `iso_code` string, nullable — ISO 3166-1 alpha-3 country code. Populated only for sovereign countries. Null for OWID aggregate entities (regions, income groups, sectoral groups).
      - `first_year` integer, nullable — Earliest year for which this entity has at least one populated column.
      - `last_year` integer, nullable — Latest year for which this entity has at least one populated column.
    - `entity_count` integer, required — Total number of entities in the bundle.
    - `country_count` integer, required — Number of entities carrying an ISO 3166-1 alpha-3 code.
    - `region_count` integer, required — Number of OWID aggregate entities without an ISO code (regions, income groups, sectoral aggregates).
    - `year_range` object, required — Minimum and maximum year in the bundle, as `{min, max}`.
    - `metric_count` integer, required — Number of metric columns (excludes identifier columns `country`, `year`, `iso_code`).
    - `metrics` string[], required — Whitelist of metric column names accepted by the `/country/{iso3}/{metric}` and `/top` endpoints.
    - `regions` string[], required — Whitelist of region names accepted by the `/region/{region}` endpoint.
    - `dataset_last_modified` string, nullable — Upstream Last-Modified timestamp for the source CSV (ISO 8601 UTC).
    - `attribution` string, required — CC BY 4.0 attribution string combining Our World in Data and the primary upstream providers cited in the codebook.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/d3e3d9c28132/schema)