# Vehicle Reference Scraper (`moving_beacon-owner1/vehicle-reference-scraper`) Actor

Scrapes vehicle specifications and safety data from public US government APIs, capturing VIN details, make and model information, EPA fuel economy, engine and drivetrain configurations, NHTSA crash-test ratings, recalls, complaints, and investigations across model, VIN, makes, and models modes.

- **URL**: https://apify.com/moving_beacon-owner1/vehicle-reference-scraper.md
- **Developed by:** [Jamshaid Arif](https://apify.com/moving_beacon-owner1) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $9.99 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Vehicle Reference Scraper

**This is a vehicle SPECIFICATION / SAFETY / RECALL reference source. It is NOT
a for-sale vehicle listings source.** There are no prices, no mileage, no
dealers and no inventory here. Every record describes a *model* or a *VIN* — its
factory specs, its EPA fuel economy, its NHTSA crash-test stars and its recall
history. If you need cars currently on sale, use a marketplace actor instead.

Data comes from three public US government web services, all keyless:

| Source | What it gives |
| --- | --- |
| NHTSA vPIC — `vpic.nhtsa.dot.gov/api/vehicles` | VIN decoding (make, model, trim, engine, body, plant, safety equipment), make and model lists per model year |
| NHTSA — `api.nhtsa.gov` | 5-Star Safety Ratings (overall / front / side / rollover), recall campaigns, owner complaint counts, investigation counts |
| fueleconomy.gov — `www.fueleconomy.gov/ws/rest/vehicle` | EPA city / highway / combined MPG, annual fuel cost, CO2 tailpipe grams per mile, greenhouse-gas and smog scores, drivetrain, transmission, EPA vehicle class |

No API key, no account and no sign-up. The actor runs against the live services
on every run.

### Modes

| `mode` | Needs | Returns |
| --- | --- | --- |
| `model` | `year`, `make`, `model` | One record per EPA fuel-economy configuration (engine / transmission combination) for that vehicle, each enriched with the NHTSA safety rating, recall count and complaint count |
| `vin` | `vins` | One record per VIN — the full vPIC decode, enriched with the safety rating, recall count and complaint count for the year/make/model the VIN resolves to |
| `makes` | `year` (optional) | One record per make. With a year, the makes fueleconomy.gov lists for that model year; without a year, the full NHTSA vPIC make list |
| `models` | `year`, `make` | One record per model NHTSA vPIC lists for that make and model year, with numeric make and model IDs |

Set `include_safety` or `include_recalls` to `false` to skip those extra lookups
and run faster.

### Output

One flat snake_case record per vehicle (per VIN in `vin` mode, per
fueleconomy.gov vehicle ID in `model` mode), plus a `raw` field holding the
untouched upstream payload. All records from one mode carry the same keys;
the samples below leave out the ones that are empty in that mode.

#### Sample — `mode: "model"`, year 2020, make Honda, model Accord

```json
{
  "record_type": "model",
  "source": "fueleconomy_gov",
  "source_url": "https://www.fueleconomy.gov/feg/Find.do?action=sbs&id=42071",
  "model_year": 2020,
  "make": "Honda",
  "model": "Accord",
  "epa_configuration": "Auto (AV-S7), 4 cyl, 1.5 L, Turbo",
  "drive_type": "Front-Wheel Drive",
  "engine_cylinders": 4,
  "displacement_l": 1.5,
  "engine_descriptor": "SIDI",
  "fuel_type_primary": "Regular Gasoline",
  "transmission_style": "Automatic (AV-S7)",
  "fueleconomy_id": 42071,
  "epa_vehicle_class": "Large Cars",
  "mpg_city": 29.0,
  "mpg_highway": 35.0,
  "mpg_combined": 31.0,
  "annual_fuel_cost_usd": 2100.0,
  "co2_tailpipe_gpm": 282.0,
  "ghg_score": 7,
  "smog_score": 7,
  "is_turbocharged": true,
  "is_supercharged": false,
  "start_stop": "N",
  "nhtsa_model": "ACCORD",
  "safety_vehicle_id": 14818,
  "safety_vehicle_description": "2020 Honda ACCORD 4 DR FWD",
  "safety_overall_rating": 5,
  "safety_front_crash_rating": 5,
  "safety_side_crash_rating": 5,
  "safety_rollover_rating": 5,
  "safety_rollover_possibility": 0.093,
  "nhtsa_electronic_stability_control": "Standard",
  "nhtsa_forward_collision_warning": "Standard",
  "nhtsa_lane_departure_warning": "Standard",
  "recall_count": 5,
  "latest_recall_campaign": "26V332000",
  "latest_recall_component": "AIR BAGS:SENSOR:OCCUPANT CLASSIFICATION:FRONT PASSENGER",
  "complaint_count": 362,
  "investigation_count": 1
}
```

#### Sample — `mode: "vin"`, VIN `5YJ3E1EA6PF384836`

```json
{
  "record_type": "vin",
  "source": "nhtsa_vpic",
  "source_url": "https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/5YJ3E1EA6PF384836?format=json",
  "vin": "5YJ3E1EA6PF384836",
  "vin_pattern": "5YJ3E1EA*PF",
  "model_year": 2023,
  "make": "TESLA",
  "model": "Model 3",
  "manufacturer": "TESLA, INC.",
  "vehicle_type": "PASSENGER CAR",
  "body_class": "Sedan/Saloon",
  "doors": 4,
  "seats": 5,
  "seat_rows": 2,
  "fuel_type_primary": "Electric",
  "electrification_level": "BEV (Battery Electric Vehicle)",
  "battery_type": "Lithium-Ion/Li-Ion",
  "transmission_style": "Automatic",
  "transmission_speeds": 1,
  "gvwr": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)",
  "curb_weight_lb": 4048,
  "plant_city": "FREMONT",
  "plant_state": "CALIFORNIA",
  "plant_country": "UNITED STATES (USA)",
  "abs": "Standard",
  "esc": "Standard",
  "tpms": "Direct",
  "backup_camera": "Standard",
  "blind_spot_monitor": "Standard",
  "air_bag_front": "1st Row (Driver and Passenger)",
  "air_bag_side": "1st and 2nd Rows",
  "decode_status_code": "0",
  "decode_status_text": "0 - VIN decoded clean. Check Digit (9th position) is correct",
  "nhtsa_model": "MODEL 3",
  "recall_count": 12,
  "latest_recall_campaign": "26V507000",
  "latest_recall_component": "EXTERIOR LIGHTING:HEADLIGHTS",
  "complaint_count": 425
}
```

#### Sample — `mode: "models"`, year 2020, make Honda

```json
{
  "record_type": "model_name",
  "source": "nhtsa_vpic",
  "source_url": "https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/Honda/modelyear/2020?format=json",
  "model_year": 2020,
  "make": "HONDA",
  "make_id": 474,
  "model": "Accord",
  "model_id": 1861
}
```

### Notes on the data

- `safety_*` fields are populated only where NHTSA actually crash-tested that
  year/make/model. Older or unrated vehicles come back with `null` stars even
  though the rest of the record is complete — that is NHTSA's own coverage, not
  a scrape failure.
- `mode: "model"` returns one row per drivetrain configuration, so a single
  nameplate typically yields several rows (the 2020 Accord returns five).
- `make_id` is `null` in `mode: "makes"` when the year-scoped make list comes
  from fueleconomy.gov, which does not publish numeric make IDs. Run `makes`
  without a year to get NHTSA vPIC make IDs instead.
- Model names differ between the two agencies. NHTSA uses `Accord`;
  fueleconomy.gov also lists `Accord Hybrid` and `Accord 2.0T Sport/Touring` as
  separate models, and folds drive and trim into names such as `RAV4 AWD LE`.
  Use `mode: "models"` to see NHTSA's names. `nhtsa_model` is the NHTSA model
  the safety, recall and complaint fields were looked up under (`RAV4` for
  `RAV4 AWD LE`). When NHTSA has no model of that name for the make and year,
  `nhtsa_model` is empty and `recall_count` / `complaint_count` are `null`
  (unknown), not `0`.
- NHTSA rates each body and drivetrain separately (for example `2020 Toyota
  CAMRY 4 DR FWD` and `... 4 DR AWD`). The `safety_*` fields come from the
  variant whose drive (and door count, where known) matches the record, and
  `safety_vehicle_description` names it. When the record does not say enough to
  pick one variant — common in VIN decodes, which often omit the drive type —
  the `safety_*` fields are left empty rather than filled from a guessed variant.
- `latest_recall_campaign` / `latest_recall_component` are the campaign NHTSA
  received most recently for that year/make/model.
- `trim` is the VIN-decoded trim and is only filled in `vin` mode;
  fueleconomy.gov publishes no trim. In `model` mode `epa_configuration` holds
  the EPA's label for the engine / transmission configuration (for example
  `Auto (AV-S7), 4 cyl, 1.5 L, Turbo`).
- `engine_model` is the manufacturer engine code from the VIN decode (`vin`
  mode). `engine_descriptor` is the EPA engine technology note from
  fueleconomy.gov (`model` mode), e.g. `SIDI` (direct injection), `PHEV`, `FFV`.
- `electrification_level` is filled only for electrified vehicles (hybrid,
  plug-in hybrid, battery-electric, fuel-cell); diesel, flex-fuel and CNG
  vehicles leave it empty and show their fuel in `fuel_type_primary`.
- `mpg_city` / `mpg_highway` / `mpg_combined` are the EPA figures on the
  primary fuel: miles per gallon-equivalent (MPGe) for battery-electric
  vehicles and the gasoline-only figure for plug-in hybrids.
  `electric_range_miles` is the EPA all-electric range (the electric-only range
  for plug-in hybrids).
- `ghg_score` and `smog_score` are EPA scores from 1 (worst) to 10 (best).
  `safety_rollover_possibility` is NHTSA's rollover risk as a fraction
  (`0.093` = 9.3%).

### Proxy

`proxyConfiguration` is optional and off by default — these are public
government services. If your network cannot reach them, set a US proxy and it is
applied to every request the actor makes. A run that cannot reach a service
fails with the reason rather than returning partial or placeholder rows.

### Input example

```json
{
  "mode": "model",
  "year": "2020",
  "make": "Honda",
  "model": "Accord",
  "include_safety": true,
  "include_recalls": true,
  "limit": 20
}
```

# Actor input Schema

## `mode` (type: `string`):

What to look up. 'model' returns EPA fuel-economy records for a year/make/model. 'vin' decodes a list of VINs. 'makes' lists every make for a model year. 'models' lists every model for a make and model year.

## `vins` (type: `string`):

Used by mode 'vin' only. One 17-character VIN per line (commas also work).

## `year` (type: `string`):

Four-digit model year, e.g. 2020. Required by modes 'model' and 'models'; optional for 'makes'.

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

Vehicle make, e.g. Honda, Toyota, Ford. Required by modes 'model' and 'models'.

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

Vehicle model, e.g. Accord, Camry, F150. Required by mode 'model'.

## `include_safety` (type: `boolean`):

Add NHTSA 5-Star Safety Ratings (overall, front, side, rollover) to each record where NHTSA rated that year/make/model.

## `include_recalls` (type: `boolean`):

Add the recall campaign count, the most recent campaign, and the owner-complaint count for each record's year/make/model.

## `limit` (type: `integer`):

Maximum number of records to return.

## `proxyConfiguration` (type: `object`):

Optional proxy. These are public US government services; a proxy is only needed if your network cannot reach them.

## Actor input object example

```json
{
  "mode": "model",
  "vins": "5YJ3E1EA6PF384836\n1HGCM82633A004352",
  "year": "2020",
  "make": "Honda",
  "model": "Accord",
  "include_safety": true,
  "include_recalls": true,
  "limit": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "mode": "model",
    "vins": `5YJ3E1EA6PF384836
1HGCM82633A004352`,
    "year": "2020",
    "make": "Honda",
    "model": "Accord",
    "limit": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("moving_beacon-owner1/vehicle-reference-scraper").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 = {
    "mode": "model",
    "vins": """5YJ3E1EA6PF384836
1HGCM82633A004352""",
    "year": "2020",
    "make": "Honda",
    "model": "Accord",
    "limit": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("moving_beacon-owner1/vehicle-reference-scraper").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 '{
  "mode": "model",
  "vins": "5YJ3E1EA6PF384836\\n1HGCM82633A004352",
  "year": "2020",
  "make": "Honda",
  "model": "Accord",
  "limit": 20
}' |
apify call moving_beacon-owner1/vehicle-reference-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,moving_beacon-owner1/vehicle-reference-scraper"
        }
    }
}
```

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/S9h5OvdePADJo1ZJO/builds/Dm8Yc74ImQuLQFLR8/openapi.json