# EPA Fuel Economy Vehicle Ratings (`automation-lab/epa-fuel-economy-vehicle-ratings`) Actor

Export official FuelEconomy.gov vehicle configurations by year, make, model or EPA ID with normalized MPG, fuel cost, tailpipe CO2, drivetrain and engine details.

- **URL**: https://apify.com/automation-lab/epa-fuel-economy-vehicle-ratings.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.08 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## EPA Fuel Economy Vehicle Ratings

Export **EPA fuel economy ratings** from the official FuelEconomy.gov vehicle API. Find vehicle configurations by model year, make and model, or retrieve known EPA vehicle IDs. Each default-dataset row contains city, highway and combined MPG or MPGe, fuel cost, tailpipe CO2, drivetrain, engine, and official source links.

Vehicle inventory teams can enrich model catalogs; fleet analysts can compare efficiency across trims; researchers can build repeatable snapshots of the EPA's published ratings. This Actor reads public source records, not VIN-specific owner data.

### What is included?

The Actor walks EPA's year → make → model → configuration menus, then fetches each configuration detail. Alternatively, give it known EPA IDs to retrieve directly. Both paths use the same normalized output and any supplied year, make and model filters. A vehicle *model* can have several engine/transmission configurations, each with its own ID.

### Who is it for?

- Fleet planners comparing configurations before a purchase.
- Automotive catalog managers joining EPA IDs to model-year data.
- Analysts comparing electric and gasoline vehicles with a consistent source reference.
- Scheduled data pipelines that take snapshots and compare successive datasets downstream.

This is not a historical change log: schedules run a fresh lookup; keep and compare previous datasets yourself.

### Why use this Actor?

The official FuelEconomy.gov API exposes menu choices and vehicle details separately. This Actor traverses those choices and returns one typed row per EPA configuration, with both the official vehicle ID and source link retained. That saves catalog teams from writing menu traversal, detail requests, deduplication, and MPG/MPGe field mapping for every new model year. Unlike a VIN decoder, it reports **EPA-rated configurations**, not a vehicle-specific build or ownership history. Filter a known ID directly when you already have an EPA key, or discover configurations by year/make/model when you do not. It does not claim to outperform other Store actors in coverage or update frequency.

### Which fields are exported?

| Field | Meaning |
| --- | --- |
| `vehicleId`, `year`, `make`, `model` | EPA configuration identifier and model identity. |
| `cityMpg`, `highwayMpg`, `combinedMpg` | EPA primary fuel ratings; for electric vehicles these can represent MPGe. |
| `alternateFuelCity`, `alternateFuelHighway`, `alternateFuelCombined` | Alternate-fuel ratings; zero can mean not applicable. |
| `fuelType`, `alternateFuelType` | EPA's fuel descriptions. |
| `annualFuelCostUsd` | EPA's annual estimate, **not** a quote for your own driving. |
| `tailpipeCo2GramsPerMile` | Direct tailpipe emissions; not full lifecycle emissions. |
| `drive`, `transmission`, `cylinders`, `engineLiters`, `electricMotor`, `vehicleClass` | Powertrain and vehicle descriptions, nullable when unavailable. |
| `sourceUrl`, `vehiclePageUrl`, `sourceUpdatedAt`, `retrievedAt` | Provenance and retrieval dates. |

### How do I get started?

1. Set a model year, such as `2024`.
2. Optionally narrow to EPA's exact make `Toyota` and model `Prius`.
3. Set `maxItems` to limit configurations and run the Actor.
4. Open the **Vehicle ratings** dataset view or download JSON, CSV or Excel from the run's default dataset.
5. Retain `vehicleId` and `sourceUrl` when joining records to your own vehicle table.

For direct lookup, omit year/make/model and provide `vehicleIds: ["47243"]`.

### What input options are available?

| Input | Use |
| --- | --- |
| `year` | EPA model year; required when using make or model. |
| `make` | Exact EPA make name; year required. |
| `model` | Exact EPA model name; year and make required. |
| `vehicleIds` | One or more numeric EPA IDs; can be combined with search. |
| `maxItems` | Maximum candidate configurations, 1–500, default 25. |

When year is supplied with IDs, the year also starts menu discovery; the IDs and discovered configurations are deduplicated. Filters apply to both. Use only IDs when you do not want discovery. The limit counts candidates before detail filters, so a mismatched ID can reduce output below the limit. A broad year-only request stops at the first `maxItems` configurations in EPA menu order, not a random or complete nationwide sample.

### What does a record look like?

This is from the EPA 2024 Toyota Prius record with ID `47243` (2026-09-24 retrieval); timestamps can change:

```json
{
  "vehicleId": "47243",
  "year": 2024,
  "make": "Toyota",
  "model": "Prius",
  "cityMpg": 57,
  "highwayMpg": 56,
  "combinedMpg": 57,
  "fuelType": "Regular",
  "annualFuelCostUsd": 1150,
  "tailpipeCo2GramsPerMile": 155,
  "drive": "Front-Wheel Drive",
  "engineLiters": 2,
  "sourceUrl": "https://www.fueleconomy.gov/ws/rest/vehicle/47243"
}
```

The actual dataset also includes the remaining fields in the schema. Missing source values are `null`; alternate-fuel values can be zero when not applicable.

### How much does it cost to export EPA vehicle ratings?

This Actor charges **$0.005 per start** and one `item` event per saved configuration. At the BRONZE spend tier, an item costs **$0.003464**. At FREE it costs $0.0039836; SILVER $0.0027019; GOLD, PLATINUM and DIAMOND $0.0020784 each. Tiers depend on qualifying aggregate monthly Apify Store spend, not the number of this Actor's items.

Estimated BRONZE totals: one record $0.008464; five $0.02232; ten $0.03964; 25 $0.0916; 100 $0.3514. A filtered-out result is not charged as an item. Apify compute and API transport are not separately billed to you by this Actor. These are estimates, not guaranteed invoices; adjustments, refunds, fraud, disputes, taxes, corrections, and contractual clawbacks can affect creator payouts. Check the live **Pricing** tab before large jobs.

### How do scheduled comparisons work?

Set an Apify schedule with a fixed input such as `{"year":2024,"make":"Tesla","maxItems":8}`. Export each run's dataset to your own storage and compare `vehicleId` plus `sourceUpdatedAt` and the fields of interest. This Actor does **not** send change alerts, retain prior snapshots, or determine what changed between runs.

### How can I enrich an existing catalog?

If your catalog already contains EPA IDs, supply `vehicleIds`. For a named model, query the year/make/model menu, then join `vehicleId`, year, make and model with your own catalog. EPA does not guarantee that one model string maps to one configuration. Avoid merging distinct drivetrain or transmission rows into one rating.

### Integrations: how do ratings reach a catalog or fleet report?

1. **Catalog enrichment:** Export the Actor's default dataset as JSON using the Apify API or a dataset integration. Join on your stored `vehicleId` where available; otherwise review the candidate rows by `year`, `make`, `model`, `drive` and `transmission` before mapping a product to one EPA configuration. Store `sourceUrl` alongside the rating for auditability.
2. **Fleet comparison:** Run once per model-year/make of interest, then send the resulting dataset to a spreadsheet or warehouse. Group by `fuelType` and configuration, compare `combinedMpg` with the appropriate MPG/MPGe unit, and use `annualFuelCostUsd` only as EPA's standardized estimate, not your fleet's realized cost.
3. **Recurring snapshot pipeline:** Schedule the same input on Apify, export each run's dataset to your own storage with its run date, and compare rows by `vehicleId`. Implement the diff and any notifications downstream; this Actor neither retains prior runs nor sends alerts.

### Can I call it through the Apify API?

Yes. Replace `YOUR_APIFY_TOKEN` with your own token and keep it out of committed files. The sync endpoint returns the default dataset items:

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~epa-fuel-economy-vehicle-ratings/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"year":2024,"make":"Toyota","model":"Prius","maxItems":10}'
```

JavaScript:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/epa-fuel-economy-vehicle-ratings').call({
    vehicleIds: ['47243'], maxItems: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Python:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/epa-fuel-economy-vehicle-ratings').call(
    run_input={'vehicleIds': ['47243'], 'maxItems': 1}
)
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Can I use this with MCP?

For Claude Code, install Apify's hosted MCP endpoint scoped to this Actor:

```bash
claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/epa-fuel-economy-vehicle-ratings'
```

For Claude Desktop, Cursor, and VS Code, configure the equivalent HTTP MCP endpoint in the editor's MCP settings:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/epa-fuel-economy-vehicle-ratings"
    }
  }
}
```

Example prompt: “Get EPA vehicle ID 47243 and explain the combined MPG, annual fuel cost and tailpipe CO2, citing the source URL.” Your MCP client may require Apify authentication.

### What are the source limits?

The official API may revise ratings, model labels or yearly coverage. MPG and MPGe are different physical measures; interpret EPA's fuel type before comparing vehicles. Annual fuel cost depends on EPA's standardized assumptions, not current local pump prices. Tailpipe CO2 does not include fuel production or electricity generation. This Actor does not decode VINs or promise tax-credit eligibility.

### How are API failures handled?

Transient timeouts, network failures, HTTP 429 and server errors receive up to two bounded retries with backoff. Invalid IDs, permanent HTTP errors, and unrecognized data shapes fail rather than silently fabricating rows. An unknown but validly requested model can return an empty dataset. Reduce the scope and verify the spelling against EPA's exact model names if that happens.

### What happens to data and how can I get help?

The Actor uses no AI provider, personal accounts, paid third-party API, proxy, external cache, or persistent cross-run state. Input IDs, normalized EPA records, and operational logs remain in Apify storage under your account's retention settings. Delete runs and datasets through Apify's storage controls. Errors may include an official EPA URL or status but do not log secret tokens. For product issues, use the Actor's Apify Store issue form with the run ID and non-sensitive input details.

### Is this data legal to use?

The Actor accesses the public U.S. government FuelEconomy.gov API. Follow the source's terms and attribution guidance; check downstream licensing and suitability for your own application. Avoid presenting EPA estimates as your own certification or personalized guarantee. No login or private consumer data is collected.

### FAQ

**Why do I get fewer rows than `maxItems`?** EPA may have fewer configurations for your filter, or an explicit ID may be excluded by the same filter. `maxItems` is a ceiling, not a target.

**Why is an EV's rating shown under `cityMpg`?** EPA's primary `city08` field can represent MPGe on electric vehicles. Check `fuelType` when interpreting units.

**Why do some alternate fields contain zero?** EPA reports zero in non-applicable alternate-fuel fields; zero is not an independently measured fuel rating.

**Can I monitor changes automatically?** Schedule runs and compare stored datasets downstream; no built-in diff or notification is emitted.

### Related tools

For other U.S. environmental datasets, see [EPA Air Quality & AQI Lookup](https://apify.com/automation-lab/epa-air-quality-aqi-lookup). Air quality observations are a separate product from vehicle fuel-economy ratings.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/epa-fuel-economy-vehicle-ratings/changelog.md

# Actor input Schema

## `year` (type: `integer`):

EPA model year to search. Required for make or model search; optional when using vehicle IDs.

## `make` (type: `string`):

Exact EPA make name, for example Toyota. Requires model year.

## `model` (type: `string`):

Exact EPA model name, for example Prius. Requires make and year.

## `vehicleIds` (type: `array`):

Optional EPA vehicle ID list. IDs are combined with search results, deduplicated, and filtered by any year/make/model provided.

## `maxItems` (type: `integer`):

Stop after up to this many candidate EPA configurations, including those excluded by filters.

## Actor input object example

```json
{
  "year": 2024,
  "make": "Toyota",
  "model": "Prius",
  "maxItems": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

EPA MPG, fuel, emissions, engine, and source records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "year": 2024,
    "make": "Toyota",
    "model": "Prius",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/epa-fuel-economy-vehicle-ratings").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "year": 2024,
    "make": "Toyota",
    "model": "Prius",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/epa-fuel-economy-vehicle-ratings").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "year": 2024,
  "make": "Toyota",
  "model": "Prius",
  "maxItems": 10
}' |
apify call automation-lab/epa-fuel-economy-vehicle-ratings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/epa-fuel-economy-vehicle-ratings"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/y1iWvKAAxnnBNq5K7/builds/2nDVOliXhkYXmZY36/openapi.json