Vehicle Fuel Economy

Overview

Either `make` or `model` is required. `make` is matched after dropping punctuation and case, with Chevy, VW and Mercedes accepted; `model` matches the start or any part of the EPA's full model name or base model, so `model=Camry` returns Camry, Camry Hybrid LE and Camry AWD LE/SE. A model without a make searches every make that builds it. `year` and `fuelType` narrow the result, and results are ordered newest model year first, then by model name; `limit` (default 20, at most 50) and `page` walk through them.

The data is fueleconomy.gov's vehicles file, rebuilt weekly, joined to its emissions file for the smog rating (the federal rating where a vehicle has both a federal and a California one). Each row is one EPA test configuration: a model year, engine, transmission and drive. `mpg` is the EPA's adjusted label value on the primary fuel, in MPGe for electric vehicles; plug-in hybrids show gasoline MPG in `mpg` and MPGe on electricity in `mpgAlternateFuel`, with their charge-depleting electric range in `electric.rangeMiles`.

`powertrain` is derived from the EPA's alternative fuel type and fuel: electric, plugin_hybrid, hybrid, hydrogen, flex_fuel, cng, diesel or gasoline. Values the EPA leaves blank or zero are null. No match returns 404. On the Free plan kWh per 100 miles, charge times, the onboard charger, annual fuel cost, five-year savings, CO2 and scores are null.

Live Test Vehicle Fuel Economy API →

Endpoint

One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.

1
2

curl "https://api.apiverve.com/v1/vehiclefueleconomy?make=Tesla&model=Model%203&year=2024&fuelType=electric&limit=20&page=1" \
  -H "x-api-key: your_api_key_here"

1
2
3
4
5
6
7
8

const res = await fetch('https://api.apiverve.com/v1/vehiclefueleconomy?make=Tesla&model=Model%203&year=2024&fuelType=electric&limit=20&page=1', {
  headers: { 'x-api-key': 'your_api_key_here' },
});

if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { data } = await res.json();
console.log(data);

1
2
3
4
5
6
7
8
9
10

import requests

res = requests.get(
    "https://api.apiverve.com/v1/vehiclefueleconomy?make=Tesla&model=Model%203&year=2024&fuelType=electric&limit=20&page=1",
    headers={"x-api-key": "your_api_key_here"},
    timeout=15,
)
res.raise_for_status()

print(res.json()["data"])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/vehiclefueleconomy?make=Tesla&model=Model%203&year=2024&fuelType=electric&limit=20&page=1", nil)
	req.Header.Set("x-api-key", "your_api_key_here")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.

Authentication

Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.

Parameters

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.

Response

Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

{
  "status": "ok",
  "error": null,
  "data": {
    "count": 5,
    "page": 1,
    "pages": 3,
    "returned": 2,
    "vehicles": [
      {
        "epaId": 47908,
        "year": 2024,
        "make": "Tesla",
        "model": "Model 3 Long Range AWD",
        "baseModel": "Model 3",
        "vehicleClass": "Midsize Cars",
        "powertrain": "electric",
        "fuelType": "Electricity",
        "drive": "All-Wheel Drive",
        "transmission": "Automatic (A1)",
        "engine": {
          "cylinders": null,
          "displacementL": null,
          "turbocharged": false,
          "supercharged": false,
          "description": null,
          "electricMotor": "84 and 191 kW ACPM 3-Phase"
        },
        "startStop": false,
        "mpg": {
          "unit": "MPGe",
          "city": 137,
          "highway": 124,
          "combined": 130
        },
        "mpgAlternateFuel": null,
        "electric": {
          "rangeMiles": 342,
          "rangeCityMiles": 357,
          "rangeHighwayMiles": 323,
          "rangeKm": 550,
          "kwhPer100Miles": {
            "city": 24.7,
            "highway": 27.2,
            "combined": 25.8
          },
          "chargeTime240vHours": 9.4,
          "chargeTime120vHours": null,
          "onboardCharger": null
        },
        "annualFuelCostUsd": 600,
        "fiveYearSavingsUsd": 8000,
        "co2GramsPerMile": 0,
        "scores": {
          "fuelEconomy": 10,
          "greenhouseGas": 10,
          "smog": 10
        },
        "gasGuzzler": false
      },
      {
        "epaId": 48473,
        "year": 2024,
        "make": "Tesla",
        "model": "Model 3 Long Range AWD-E",
        "baseModel": "Model 3",
        "vehicleClass": "Midsize Cars",
        "powertrain": "electric",
        "fuelType": "Electricity",
        "drive": "All-Wheel Drive",
        "transmission": "Automatic (A1)",
        "engine": {
          "cylinders": null,
          "displacementL": null,
          "turbocharged": false,
          "supercharged": false,
          "description": null,
          "electricMotor": "191 kW ACPM 3-Phase"
        },
        "startStop": false,
        "mpg": {
          "unit": "MPGe",
          "city": 133,
          "highway": 122,
          "combined": 128
        },
        "mpgAlternateFuel": null,
        "electric": {
          "rangeMiles": 341,
          "rangeCityMiles": 355,
          "rangeHighwayMiles": 324,
          "rangeKm": 549,
          "kwhPer100Miles": {
            "city": 25.3,
            "highway": 27.7,
            "combined": 26.4
          },
          "chargeTime240vHours": 10,
          "chargeTime120vHours": null,
          "onboardCharger": null
        },
        "annualFuelCostUsd": 600,
        "fiveYearSavingsUsd": 8000,
        "co2GramsPerMile": 0,
        "scores": {
          "fuelEconomy": 10,
          "greenhouseGas": 10,
          "smog": 10
        },
        "gasGuzzler": false
      }
    ]
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.

Use cases

Car Shopping Sites

Show EPA MPG, EV range and running costs beside each listing and let buyers compare trims.

Fleet Electrification

Compare the annual fuel cost and CO2 of current vehicles against electric replacements.

Insurance and Finance

Add powertrain, fuel type and efficiency to vehicle records for pricing and green-loan eligibility.

Sustainability Reporting

Estimate tailpipe CO2 per mile for company cars and mileage claims.

Other ways to use Vehicle Fuel Economy

Set up Vehicle Fuel Economy on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.

Related

More in Transportation: