---
title: "CO2 breakdown by source for one country"
method: GET
path: "/api/v1/environment/co2/sources/{iso3}"
tags: ["Environment"]
---

# CO2 breakdown by source for one country

`GET /api/v1/environment/co2/sources/{iso3}`

Returns annual CO2 emissions by source for one ISO 3166-1 alpha-3 coded country. Sources: coal, oil, natural gas, cement, gas flaring, other industrial processes, and land-use change. Values are in million tonnes of CO2 per year. Land-use change can be negative for countries with net forest sequestration. Compiled by the Global Carbon Project (Global Carbon Budget 2025) and redistributed by Our World in Data. Published under CC BY 4.0 with dual attribution.

## Path parameters

- `iso3` string, required — ISO 3166-1 alpha-3 country code. Case-insensitive; normalised to uppercase.

## Query parameters

- `start_year` integer, nullable — Inclusive start year (integer). Bundle range is 1750-present; source columns populate from 1850 onwards.
- `end_year` integer, nullable — Inclusive end year. Defaults to the latest year in the bundle.

## Response `200`

Annual CO2 breakdown by fossil source and land-use change.

- EnvelopeCo2SourcesPayload
  - `data` Co2SourcesPayload, required — CO2 breakdown by source (coal, oil, gas, cement, flaring, other, LUC).
    - `iso_code` string, required — ISO 3166-1 alpha-3 code echoed from the path parameter, uppercased.
    - `country` string, nullable — Country name as published by OWID.
    - `unit` string — Unit applied to every numeric field in the breakdown.
    - `observations` Co2SourceRow[], required — Yearly breakdown rows ordered ascending by year.
      - `year` integer, required — Observation year.
      - `coal` number, nullable — Annual CO2 emissions from coal combustion, million tonnes. Sourced from the Global Carbon Budget.
      - `oil` number, nullable — Annual CO2 emissions from oil combustion, million tonnes.
      - `gas` number, nullable — Annual CO2 emissions from natural-gas combustion, million tonnes.
      - `cement` number, nullable — Annual process CO2 emissions from cement production, million tonnes.
      - `flaring` number, nullable — Annual CO2 emissions from gas flaring, million tonnes.
      - `other_industry` number, nullable — Annual CO2 emissions from other industrial processes not captured above, million tonnes.
      - `land_use_change` number, nullable — Annual CO2 emissions from land-use change and forestry, million tonnes. Separate from fossil emissions; can be negative for countries with net sequestration.
    - `count` integer, required — Number of observations in the response.
    - `attribution` string, required — CC BY 4.0 attribution string naming OWID and the Global Carbon Project.
  - `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.
- `422` — Validation Error
- `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/4e2740743eb4/schema)