# 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"
```

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

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

#### `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"
```

#### `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"
```

#### `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"
```


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