---
title: "Full column dictionary for the OWID CO2 bundle"
method: GET
path: "/api/v1/environment/co2/codebook"
tags: ["Environment"]
---

# Full column dictionary for the OWID CO2 bundle

`GET /api/v1/environment/co2/codebook`

Returns the column dictionary shipped with the bundle - one row per column with title, description, unit, and the primary upstream source. The codebook is OWID's authoritative schema definition and is the correct place to discover available metrics, their units, and methodological caveats before using them in `/country/{iso3}/{metric}` or `/top`. Published under CC BY 4.0 with dual attribution to Our World in Data and the primary upstream providers named per column.

## Response `200`

Column dictionary with title, description, unit, and source per column.

- EnvelopeCo2CodebookPayload
  - `data` Co2CodebookPayload, required — Full column dictionary with unit and upstream source per column.
    - `columns` Co2CodebookColumn[], required — One entry per column in the CSV bundle.
      - `column` string, required — CSV column name (machine-readable identifier).
      - `title` string, nullable — Human-readable title.
      - `description` string, nullable — Long description with methodological caveats.
      - `unit` string, nullable — Unit of measure.
      - `source` string, nullable — Primary upstream data provider cited by OWID for this column.
    - `count` integer, required — Number of columns in the codebook.
    - `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 naming OWID and the set of primary upstream providers.
  - `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/4c4530760ba1/schema)