# Carbon Footprint API
> Estimate CO2e emissions for everyday activities using the official DEFRA 2023 GHG conversion factors: road and rail travel (per kilometre by vehicle type, split across passengers), flights (by airport IATA pair with great-circle distance, or by distance, across cabin classes and round trips), grid electricity (by kilowatt-hour and country carbon intensity) and direct fuel combustion (by litres and fuel type). A factors endpoint exposes every emission factor, supported vehicle and fuel type, and the country grid-intensity table. Each result returns CO2e in kilograms, tonnes and grams. Every endpoint accepts input via the query string or the request body and returns lean JSON. Pure server-side compute (no third-party upstream), so responses are instant and always available. Ideal for travel and booking flows, sustainability dashboards, ESG and Scope-3 reporting, and carbon-aware product features.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/carbonfootprint-api/..."
```

## Pricing
- **Free** (Free) — 22,000 calls/Mo, 3 req/s
- **Basic** ($8/Mo) — 280,000 calls/Mo, 12 req/s
- **Pro** ($23/Mo) — 2,200,000 calls/Mo, 40 req/s
- **Mega** ($58/Mo) — 11,000,000 calls/Mo, 120 req/s

## Endpoints

### Carbon

#### `GET /v1/electricity` — Grid electricity emissions

**Parameters:**
- `kwh` (query, required, string) — Energy in kWh Example: `1000`
- `country` (query, optional, string) — ISO-2 country code or WORLD Example: `DE`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonfootprint-api/v1/electricity?kwh=1000&country=DE"
```

**Response:**
```json
{
    "data": {
        "input": {
            "kwh": 1000,
            "country": "DE"
        },
        "co2e_g": 381000,
        "co2e_kg": 381,
        "co2e_tonnes": 0.381,
        "grid_intensity_g_per_kwh": 381
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:32.143Z",
        "request_id": "085590aa-b93f-4b1f-b24f-61adaf89c9a7"
    },
    "status": "ok",
    "message": "Electricity emissions estimated",
    "success": true
}
```

#### `GET /v1/factors` — All emission factors & options

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonfootprint-api/v1/factors"
```

**Response:**
```json
{
    "data": {
        "source": "DEFRA 2023 GHG conversion factors; grid intensities Ember/OWID 2023; airport coords OpenFlights",
        "vehicle_types": [
            "car_petrol",
            "car_diesel",
            "car_hybrid",
            "car_electric",
            "car_average",
            "motorbike",
            "bus",
            "coach",
            "train_national",
            "train_metro",
            "tram",
            "bicycle",
            "walking"
        ],
        "flight_classes": {
            "first": 4,
            "economy": 1,
            "premium": 1.6,
            "business": 2.9
        },
        "grid_countries": [
            "WORLD",
            "US",
            "GB",
            "DE",
            "FR",
            "ES",
            "IT",
            "NL",
            "BE",
            "PL",
            "SE",
            "NO",
            "DK",
            "FI",
            "CH",
            "AT",
            "IE",
            "PT",
            "GR",
            "CN",
            "IN",
            "JP",
            "KR",
            "AU",
            "CA",
            "BR",
            "RU",
            "ZA",
            "MX",
            "ID",
            "TR",
            "SA",
            "AE",
            "NG",
            "EG",
            "AR",
            "CL",
            "NZ",
            "IS",
            "PK",
            "TH",
            "VN",
            "MY",
            "PH",
            "UA"
        ],
        "airp
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/flight` — Air travel emissions

**Parameters:**
- `from` (query, optional, string) — Origin airport IATA Example: `LHR`
- `to` (query, optional, string) — Destination airport IATA Example: `JFK`
- `distance_km` (query, optional, string) — Distance (if no airports) Example: `5500`
- `class` (query, optional, string) — economy|premium|business|first Example: `economy`
- `passengers` (query, optional, string) — Passengers Example: `1`
- `round_trip` (query, optional, string) — Round trip Example: `true`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonfootprint-api/v1/flight?from=LHR&to=JFK&distance_km=5500&class=economy&passengers=1&round_trip=true"
```

**Response:**
```json
{
    "data": {
        "input": {
            "to": "JFK",
            "band": "long_haul",
            "from": "LHR",
            "class": "economy",
            "passengers": 1,
            "round_trip": true,
            "distance_km": 5539.7
        },
        "co2e_g": 1639738,
        "co2e_kg": 1639.738,
        "co2e_tonnes": 1.639738,
        "per_passenger": {
            "co2e_g": 1639738,
            "co2e_kg": 1639.738,
            "co2e_tonnes": 1.639738
        },
        "class_multiplier": 1,
        "factor_kg_per_km": 0.148
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:32.291Z",
        "request_id": "ea6f307a-6f49-4db9-8e3c-cdf9e3e7450e"
    },
    "status": "ok",
    "message": "Flight emissions estimated",
    "success": true
}
```

#### `GET /v1/fuel` — Fuel combustion emissions

**Parameters:**
- `liters` (query, required, string) — Litres of fuel Example: `40`
- `fuel_type` (query, optional, string) — petrol|diesel|lpg|kerosene|heating_oil Example: `diesel`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonfootprint-api/v1/fuel?liters=40&fuel_type=diesel"
```

**Response:**
```json
{
    "data": {
        "input": {
            "liters": 40,
            "fuel_type": "diesel"
        },
        "co2e_g": 107200,
        "co2e_kg": 107.2,
        "co2e_tonnes": 0.1072,
        "factor_kg_per_liter": 2.68
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:32.362Z",
        "request_id": "01d80ca3-7ebc-46ed-a68c-47845560da21"
    },
    "status": "ok",
    "message": "Fuel emissions estimated",
    "success": true
}
```

#### `GET /v1/vehicle` — Road/rail travel emissions

**Parameters:**
- `distance_km` (query, required, string) — Distance in km Example: `100`
- `vehicle` (query, optional, string) — car_petrol|car_diesel|car_electric|bus|train_national|... Example: `car_petrol`
- `passengers` (query, optional, string) — Split across passengers Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonfootprint-api/v1/vehicle?distance_km=100&vehicle=car_petrol&passengers=1"
```

**Response:**
```json
{
    "data": {
        "input": {
            "vehicle": "car_petrol",
            "passengers": 1,
            "distance_km": 100
        },
        "co2e_g": 17000,
        "co2e_kg": 17,
        "co2e_tonnes": 0.017,
        "per_passenger": {
            "co2e_g": 17000,
            "co2e_kg": 17,
            "co2e_tonnes": 0.017
        },
        "factor_kg_per_km": 0.17
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:32.439Z",
        "request_id": "dda06509-0601-477d-ac21-55857457182b"
    },
    "status": "ok",
    "message": "Vehicle emissions estimated",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/carbonfootprint-api
OpenAPI spec: https://www.oanor.com/api/carbonfootprint-api/openapi.json