# Nhtsa Recalls Us (`dromb/nhtsa-recalls-us`) Actor

This Apify actor provides structured access to the official National Highway Traffic Safety Administration (NHTSA) vehicle recall and complaint datasets. It allows users to search for safety recalls, view consumer complaints, and decode Vehicle Identification Numbers (VINs).

- **URL**: https://apify.com/dromb/nhtsa-recalls-us.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## NHTSA Recalls US Scraper

This Apify actor provides structured access to the official National Highway Traffic Safety Administration (NHTSA) vehicle recall and complaint datasets. It allows users to search for safety recalls, view consumer complaints, and decode Vehicle Identification Numbers (VINs).

**Note:** This actor is unofficial and is not affiliated with, endorsed by, or sponsored by NHTSA or any government agency.

### Features
- **Vehicle Search**: Find all recalls or complaints for a specific make, model, and year.
- **Direct Lookup**: Retrieve specific records using NHTSA campaign numbers, ODI numbers, or VINs.
- **Browse Hierarchy**: Navigate the dataset via a structured hierarchy: Model Years $\rightarrow$ Makes $\rightarrow$ Models $\rightarrow$ Records.
- **VIN Decoding**: Decode a VIN to get detailed vehicle specifications and manufacturer information.

### Supported Operations

#### 1. Probe (`probe`)
Verifies the connection to the NHTSA API and returns high-level coverage metadata.
- **Input Example**:
```json
{
  "operation": "probe"
}
````

#### 2. List Root Categories (`categories`)

Returns the starting points for browsing (usually model year lists for recalls and complaints).

- **Input Example**:

```json
{
  "operation": "categories"
}
```

#### 3. Browse Category (`category`)

Navigate through the hierarchy using a `category_id`.

- **Hierarchy Levels**:
  - `years:recall` or `years:complaint` $\rightarrow$ List of years.
  - `makes:recall:2012` $\rightarrow$ List of makes for 2012 recalls.
  - `models:recall:2012:BMW` $\rightarrow$ List of models for BMW 2012 recalls.
  - `records:recall:2012:BMW:3-SERIES` $\rightarrow$ List of actual recall records.
- **Input Example**:

```json
{
  "operation": "category",
  "category_id": "years:recall",
  "limit": 5
}
```

#### 4. Search (`search`)

Search for records using various filters.

**By Vehicle**:

```json
{
  "operation": "search",
  "record_type": "recall",
  "make": "Acura",
  "model": "RDX",
  "model_year": 2012,
  "limit": 5
}
```

**By Campaign Number**:

```json
{
  "operation": "search",
  "campaign_number": "12V176000",
  "limit": 5
}
```

**By ODI Complaint Number**:

```json
{
  "operation": "search",
  "odi_number": "11184030",
  "limit": 5
}
```

**By VIN**:

```json
{
  "operation": "search",
  "vin": "5YJSA1E26HF000337",
  "limit": 5
}
```

#### 5. Item Detail (`item`)

Retrieve a single detailed record by identifier.

- **Input Example**:

```json
{
  "operation": "item",
  "campaign_number": "12V176000"
}
```

### Output Schema

The actor outputs normalized records to the Apify dataset.

#### Common Output Fields

| Field | Description |
|---|---|
| `id` | Unique identifier (Campaign #, ODI #, or VIN) |
| `record_type` | Type of record: `recall`, `complaint`, or `vin` |
| `campaign_number` | NHTSA Campaign Number (for recalls) |
| `odi_number` | ODI Complaint Number (for complaints) |
| `vin` | Vehicle Identification Number |
| `make` | Vehicle manufacturer (normalized to uppercase) |
| `model` | Vehicle model (normalized to uppercase) |
| `model_year` | Vehicle model year |
| `manufacturer` | Official manufacturer name |
| `summary` | Detailed description of the issue |
| `consequence` | Potential risk or result of the issue |
| `remedy` | How the issue is fixed |
| `received_on` | Date the report was received |
| `source_url` | Link to the official NHTSA record |
| `decoded_fields` | Technical specs (for VIN decode only) |

#### Example Output (Recall)

```json
{
  "id": "12V176000",
  "record_type": "recall",
  "campaign_number": "12V176000",
  "title": "2012 BMW 3-SERIES recall 12V176000",
  "manufacturer": "BMW OF NORTH AMERICA, LLC",
  "make": "BMW",
  "model": "3-SERIES",
  "model_year": 2012,
  "component": "SEATS:FRONT ASSEMBLY:HEAD RESTRAINT",
  "summary": "BMW IS RECALLING CERTAIN MODEL YEAR 2012 BMW 3-SERIES...",
  "consequence": "IN THE EVENT OF A VEHICLE CRASH...",
  "remedy": "BMW WILL NOTIFY OWNERS...",
  "received_on": "20/04/2012",
  "source_url": "https://api.nhtsa.gov/recalls/campaignNumber?campaignNumber=12V176000",
  "source": "nhtsa_recalls_us"
}
```

### Limits and Capping

- **Default Limit**: 25 items per page.
- **Maximum Limit**: 100 items per page.
- **Pagination**: Use the `page` parameter (1-based) to retrieve subsequent results.

### Error Handling

- **Invalid Identifiers**: If a campaign, ODI, or VIN number is not found, the actor returns an empty dataset.
- **Missing Fields**: Vehicle searches require `make`, `model`, and `model_year`. Missing fields will result in an empty dataset or log warning.
- **Unknown Operation**: Blocked by the input schema validation.

### Use Cases

- **Recall Monitoring**: Automatically track new recalls for specific vehicle fleets.
- **VIN Auditing**: Decode VINs to verify vehicle specifications for insurance or sales.
- **Safety Research**: Analyze consumer complaints (ODI) for specific models.
- **Market Analysis**: Discover available models and makes via the category hierarchy.

# Actor input Schema

## `operation` (type: `string`):

The operation to perform.

## `search_type` (type: `string`):

Type of search to perform. Used as a hint for the search operation.

## `query` (type: `string`):

Direct identifier alias for campaign number, ODI number, or VIN.

## `record_type` (type: `string`):

One of recall, complaint, or vin.

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

Vehicle make for vehicle-based recall or complaint search.

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

Vehicle model for vehicle-based recall or complaint search.

## `model_year` (type: `integer`):

Vehicle model year for vehicle-based recall or complaint search.

## `campaign_number` (type: `string`):

Direct recall lookup by NHTSA campaign number.

## `odi_number` (type: `string`):

Direct complaint lookup by ODI number.

## `vin` (type: `string`):

Direct VIN decode lookup.

## `category_id` (type: `string`):

Browse category id (e.g., years:recall, makes:recall:2012).

## `page` (type: `integer`):

1-based results page.

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

Number of results per page.

## Actor input object example

```json
{
  "operation": "search",
  "record_type": "recall",
  "page": 1,
  "limit": 5
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("dromb/nhtsa-recalls-us").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("dromb/nhtsa-recalls-us").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call dromb/nhtsa-recalls-us --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dromb/nhtsa-recalls-us",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Nhtsa Recalls Us",
        "description": "This Apify actor provides structured access to the official National Highway Traffic Safety Administration (NHTSA) vehicle recall and complaint datasets. It allows users to search for safety recalls, view consumer complaints, and decode Vehicle Identification Numbers (VINs).",
        "version": "0.0",
        "x-build-id": "Hfo7CHuStEDXn8MWB"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/dromb~nhtsa-recalls-us/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-dromb-nhtsa-recalls-us",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/dromb~nhtsa-recalls-us/runs": {
            "post": {
                "operationId": "runs-sync-dromb-nhtsa-recalls-us",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/dromb~nhtsa-recalls-us/run-sync": {
            "post": {
                "operationId": "run-sync-dromb-nhtsa-recalls-us",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "operation"
                ],
                "properties": {
                    "operation": {
                        "title": "Operation",
                        "enum": [
                            "probe",
                            "search",
                            "categories",
                            "category",
                            "item"
                        ],
                        "type": "string",
                        "description": "The operation to perform.",
                        "default": "search"
                    },
                    "search_type": {
                        "title": "Search Type",
                        "enum": [
                            "vehicle",
                            "campaign",
                            "odi",
                            "vin"
                        ],
                        "type": "string",
                        "description": "Type of search to perform. Used as a hint for the search operation."
                    },
                    "query": {
                        "title": "Query",
                        "type": "string",
                        "description": "Direct identifier alias for campaign number, ODI number, or VIN."
                    },
                    "record_type": {
                        "title": "Record Type",
                        "enum": [
                            "recall",
                            "complaint",
                            "vin"
                        ],
                        "type": "string",
                        "description": "One of recall, complaint, or vin.",
                        "default": "recall"
                    },
                    "make": {
                        "title": "Make",
                        "type": "string",
                        "description": "Vehicle make for vehicle-based recall or complaint search."
                    },
                    "model": {
                        "title": "Model",
                        "type": "string",
                        "description": "Vehicle model for vehicle-based recall or complaint search."
                    },
                    "model_year": {
                        "title": "Model Year",
                        "type": "integer",
                        "description": "Vehicle model year for vehicle-based recall or complaint search."
                    },
                    "campaign_number": {
                        "title": "Campaign Number",
                        "type": "string",
                        "description": "Direct recall lookup by NHTSA campaign number."
                    },
                    "odi_number": {
                        "title": "ODI Number",
                        "type": "string",
                        "description": "Direct complaint lookup by ODI number."
                    },
                    "vin": {
                        "title": "VIN",
                        "type": "string",
                        "description": "Direct VIN decode lookup."
                    },
                    "category_id": {
                        "title": "Category ID",
                        "type": "string",
                        "description": "Browse category id (e.g., years:recall, makes:recall:2012)."
                    },
                    "page": {
                        "title": "Page",
                        "type": "integer",
                        "description": "1-based results page.",
                        "default": 1
                    },
                    "limit": {
                        "title": "Limit",
                        "type": "integer",
                        "description": "Number of results per page.",
                        "default": 5
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```