# FuelEconomy.gov API
> Official US vehicle fuel-economy data as an API, powered by FuelEconomy.gov — the joint US EPA and Department of Energy resource behind the fuel-economy window sticker on every car, SUV and truck sold in the United States since 1984. Browse the catalogue step by step — model years, then makes, then models, then the engine/transmission trims (each carrying the vehicle id you need for the detail call) — and pull a vehicle's complete fuel-economy record: city, highway and combined MPG, fuel type, engine (number of cylinders and displacement), transmission, EPA vehicle class and drivetrain, the estimated annual fuel cost, tailpipe CO2 emissions in grams per mile, the barrels of petroleum consumed per year and the estimated five-year fuel-cost saving (or extra spend) versus an average new vehicle. Ideal for car-shopping and comparison tools, total-cost-of-ownership and emissions calculators, fleet management and sustainability reporting. The data is authoritative, official EPA/DOE test data and is public domain; it covers US-market light-duty vehicles. Vehicle ids come from the trims endpoint, reached via the year -> make -> model -> trim chain.

## 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/fueleconomy-api/..."
```

## Pricing
- **Free** (Free) — 600 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 22,300 calls/Mo, 6 req/s
- **Pro** ($22/Mo) — 93,000 calls/Mo, 15 req/s
- **Mega** ($61/Mo) — 410,000 calls/Mo, 40 req/s

## Endpoints

### Vehicles

#### `GET /v1/makes` — Makes for a model year

**Parameters:**
- `year` (query, required, string) — Model year, e.g. 2020 Example: `2020`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fueleconomy-api/v1/makes?year=2020"
```

**Response:**
```json
{
    "data": {
        "year": "2020",
        "count": 50,
        "makes": [
            "Acura",
            "Alfa Romeo",
            "Aston Martin",
            "Audi",
            "Bentley",
            "BMW",
            "Bugatti",
            "Buick",
            "BYD",
            "Cadillac",
            "Chevrolet",
            "Chrysler",
            "Dodge",
            "Ferrari",
            "Fiat",
            "Ford",
            "Genesis",
            "GMC",
            "Honda",
            "Hyundai",
            "Infiniti",
            "Jaguar",
            "Jeep",
            "Karma",
            "Kia",
            "Koenigsegg",
            "Lamborghini",
            "Land Rover",
            "Lexus",
            "Lincoln",
            "Lotus",
            "Maserati",
            "Mazda",
            "McLaren Automotive",
            "Mercedes-Benz",
            "MINI",
            "Mitsubishi",
            "Nissan",
            "Pagani",
            "Polestar",
            "Porsche",
            "Ram",
            "Rolls-Royce",
            "Roush Performance",
            "RUF Automobile",
            "Subaru",
            "Tesla",
            "Toyota",
            "Volkswagen",
            "Volvo"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:55.429Z",
        "request_id": "da5884fb-cc1a-4a34-9595-ddab6d34ad19"
    },
    "status": "ok",
    "message": "Makes retrieved",
    "success": true
}
```

#### `GET /v1/models` — Models for a year & make

**Parameters:**
- `year` (query, required, string) — Model year Example: `2020`
- `make` (query, required, string) — Make, e.g. Honda Example: `Honda`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fueleconomy-api/v1/models?year=2020&make=Honda"
```

**Response:**
```json
{
    "data": {
        "make": "Honda",
        "year": "2020",
        "count": 23,
        "models": [
            "Accord",
            "Accord 2.0T Sport/Touring",
            "Accord Hybrid",
            "Civic 2Dr",
            "Civic 4Dr",
            "Civic 5Dr",
            "Clarity FCV",
            "Clarity Plug-in Hybrid",
            "CR-V AWD",
            "CR-V FWD",
            "CR-V Hybrid AWD",
            "Fit",
            "HR-V AWD",
            "HR-V FWD",
            "Insight",
            "Insight Touring",
            "Odyssey",
            "Passport AWD",
            "Passport FWD",
            "Pilot AWD",
            "Pilot FWD",
            "Ridgeline AWD",
            "Ridgeline FWD"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:55.741Z",
        "request_id": "849d201b-7fac-4224-b2e0-5f33f4be8d5e"
    },
    "status": "ok",
    "message": "Models retrieved",
    "success": true
}
```

#### `GET /v1/trims` — Trims with vehicle ids

**Parameters:**
- `year` (query, required, string) — Model year Example: `2020`
- `make` (query, required, string) — Make Example: `Honda`
- `model` (query, required, string) — Exact model name from /v1/models Example: `Accord`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fueleconomy-api/v1/trims?year=2020&make=Honda&model=Accord"
```

**Response:**
```json
{
    "data": {
        "make": "Honda",
        "year": "2020",
        "count": 5,
        "model": "Accord",
        "trims": [
            {
                "trim": "Auto (AV-S7), 4 cyl, 1.5 L, Turbo",
                "vehicle_id": "42071"
            },
            {
                "trim": "Auto (S10), 4 cyl, 2.0 L, Turbo",
                "vehicle_id": "42073"
            },
            {
                "trim": "Auto (variable gear ratios), 4 cyl, 1.5 L, Turbo",
                "vehicle_id": "42070"
            },
            {
                "trim": "Man 6-spd, 4 cyl, 1.5 L, Turbo",
                "vehicle_id": "42069"
            },
            {
                "trim": "Man 6-spd, 4 cyl, 2.0 L, Turbo",
                "vehicle_id": "42072"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:56.039Z",
        "request_id": "076ac653-14ed-4a0e-86b9-31499823b72a"
    },
    "status": "ok",
    "message": "Trims retrieved",
    "success": true
}
```

#### `GET /v1/vehicle` — Full fuel-economy record

**Parameters:**
- `id` (query, required, string) — Vehicle id from /v1/trims, e.g. 38313 Example: `38313`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fueleconomy-api/v1/vehicle?id=38313"
```

**Response:**
```json
{
    "data": {
        "vehicle": {
            "id": "38313",
            "mpg": {
                "city": 27,
                "highway": 36,
                "combined": 30
            },
            "make": "Mazda",
            "year": 2017,
            "drive": "Front-Wheel Drive",
            "model": "3 4-Door",
            "cylinders": 4,
            "fuel_type": "Regular",
            "ghg_score": 7,
            "transmission": "Automatic (S6)",
            "alt_fuel_type": null,
            "vehicle_class": "Compact Cars",
            "displacement_l": 2.5,
            "epa_size_class": "Compact Cars",
            "annual_fuel_cost_usd": 2250,
            "five_year_savings_usd": 750,
            "co2_tailpipe_g_per_mile": 293,
            "barrels_petroleum_per_year": 9.917
        }
    },
    "meta": {
        "timestamp": "2026-06-01T16:24:02.703Z",
        "request_id": "20aa276a-c27b-44a6-b5ad-2f2e2651a6d8"
    },
    "status": "ok",
    "message": "Vehicle retrieved",
    "success": true
}
```

#### `GET /v1/years` — Available model years

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

**Response:**
```json
{
    "data": {
        "count": 44,
        "years": [
            "2027",
            "2026",
            "2025",
            "2024",
            "2023",
            "2022",
            "2021",
            "2020",
            "2019",
            "2018",
            "2017",
            "2016",
            "2015",
            "2014",
            "2013",
            "2012",
            "2011",
            "2010",
            "2009",
            "2008",
            "2007",
            "2006",
            "2005",
            "2004",
            "2003",
            "2002",
            "2001",
            "2000",
            "1999",
            "1998",
            "1997",
            "1996",
            "1995",
            "1994",
            "1993",
            "1992",
            "1991",
            "1990",
            "1989",
            "1988",
            "1987",
            "1986",
            "1985",
            "1984"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:24:02.924Z",
        "request_id": "67743351-f816-4149-8a7d-6e706dcc1154"
    },
    "status": "ok",
    "message": "Years retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

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

**Response:**
```json
{
    "data": {
        "note": "Official US EPA fuel-economy ratings — the data behind the window sticker on every car sold in the US since 1984. Browse the catalogue step by step: /v1/years = the model years available; /v1/makes?year=2020 = the makes for a year; /v1/models?year=2020&make=Honda = the models for a year & make; /v1/trims?year=2020&make=Honda&model=Accord = the engine/transmission trims for a model, each with the vehicle id needed for the detail call (use the exact model name returned by /v1/models); /v1/vehicle?id=38313 = a vehicle's full fuel-economy record — city, highway and combined MPG, fuel type, engine (cylinders & displacement), transmission, vehicle class, estimated annual fuel cost, CO2 tailpipe emissions (g/mile), barrels of petroleum per year and the 5-year fuel-cost savings vs. an average vehicle. Ideal for car-shopping tools, fleet and emissions analysis, and sustainability calculators. Data is public-domain from the US EPA & DOE. Covers US-market vehicles.",
        "source": "FuelEconomy.gov — US EPA / DOE (fueleconomy.gov)",
        "endpoints": [
            "/v1/years",
            "/v1/makes",
            "/v1/models",
            "/v1/trims",
            "/v1/vehicle",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:24:02.981Z",
        "request_id": "0f12f771-4d78-4b0e-821d-1184512297e5"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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