<commit_before>---
permalink: /developer/recalls.html
layout: post
title: Recalls API
tags: recalls api
---

[USASearch](http://usasearch.howto.gov) > [APIs for Developers](/developer/index.html) > Recalls API

<a href="https://github.com/GSA-OCSIT"><img style="position: absolute; top: 41px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>

Helping alert the public to unsafe, hazardous, or defective products.

<ul>
  <li class="overview current"><a href="#overview">Overview</a></li>
  <li class="api"><a href="#using-the-api">Using the API</a></li>
  <li class="parameters"><a href="#parameters">Parameters</a></li>
  <li class="sources"><a href="#data-sources">Data Sources</a></li>
  <li class="returns"><a href="#what-it-returns">What it Returns</a></li>
</ul>

<a name="overview"></a><h2>Overview</h2>

When you're buying and using products, safety comes first.

Six federal regulatory agencies issue recalls on [Recalls.gov](http://www.recalls.gov).

This Recalls API allows you to tap into a list of (1) drug and food safety recalls from the [Food and Drug Administration](http://www.fda.gov), [Food Safety and Inspection Service](http://www.fsis.usda.gov), and [FoodSafety.gov](http://www.FoodSafety.gov); (2) car safety recalls from the [National Highway Traffic Safety Administration](http://www.nhtsa.gov); and (3) product safety recalls from the [Consumer Product Safety Commission](http://www.cpsc.gov).

This API is great for consumer safety websites or applications, news organizations, and websites or magazines targeted to specific audiences, such as parents.

<a name="using-the-api"></a><h2>Using the API</h2>

This Recalls API accepts a GET request.

Recalls are searchable by keyword, issuing agency, date, UPC code, vehicle-specific attributes, or any combination of these.

The base URL is http://api.usa.gov/recalls/search.json?**parameter**

Sample API requests follow.

All recalls  
<http://api.usa.gov/recalls/search.json?>

All cribs  
<http://api.usa.gov/recalls/search.json?query=cribs>

All cribs that pose a choking hazard  
<http://api.usa.gov/recalls/search.json?query=cribs+choking>


All cribs that pose a choking hazard sorted by date  
<http://api.usa.gov/recalls/search.json?query=cribs+choking&sort=date>

<a name="parameters"></a><h2>Parameters</h2>

Seven generic parameters are accepted: (1) `query`, (2) `organization`, (3) `start_date`, (4) `end_date`, (5) `page`, (6) `per_page`, and (7) `sort`. There are additional parameters that are specific to food, product, and car safety recalls. None are required.

### query

Attempts to extract as much "signal" as possible from the input text. Handles word variants, so a search on "choke" will find a recall categorized as a "choking" hazard.

### organization

Specifies which agency issued the recall. Possible values are `CPSC`, `FDA`, `NHTSA`, or `USDA`.

Example (one agency): <http://api.usa.gov/recalls/search.json?organization=nhtsa>

Example (multiple agencies): <http://api.usa.gov/recalls/search.json?organization=fda+usda>

### start_date

Specifies the start date of the recall.

Example: <http://api.usa.gov/recalls/search.json?start_date=2012-01-01>

### end_date

Specifies the end date of the recall.

Example: <http://api.usa.gov/recalls/search.json?end_date=2012-12-31>

### page

Specifies the pagination of search results. Possible values are `1` to `20`.

Example: <http://api.usa.gov/recalls/search.json?page=3>

### per_page

Specifies the number of search results for each page. Possible values are `1` to `50`.

Example: <http://api.usa.gov/recalls/search.json?per_page=10>

### sort

Results are sorted by relevance by default. Possible values are `rel` or `date`. Use 'sort=date' to sort results by date with the most recent listed first.

Example: <http://api.usa.gov/recalls/search.json?sort=date>

### food_type 
Only for drug and food safety recalls. Possible values are `food` or `drug`.

Example: <http://api.usa.gov/recalls/search.json?food_type=drug>

### upc

Only for CPSC recalls. Specifies the UPC code when available. Not all products have UPC codes.

Example: <http://api.usa.gov/recalls/search.json?upc=042666601627>

### make, model, year, and code (only for NHTSA recalls)

* `make` specifies the make of the vehicle or equipment. Example: <http://localhost:3000/search?make=winnebago>
* `model` specifies the model of the vehicle or equipment. Example: <http://localhost:3000/search?model=ellipse>
* `year` specifies the year of the vehicle or equipment. Example: <http://localhost:3000/search?year=2010>
* `code` specifies the NHTSA code. Possible values are `E`, `V` [for vehicles], `I`, `T`, `C`, or `X`. Example: <http://localhost:3000/search?code=v>

<a name="data-sources"></a><h2>Data Sources</h2>

Data are normalized across (1) drug and food safety recalls from the [Food and Drug Administration](http://www.fda.gov), [Food Safety and Inspection Service](http://www.fsis.usda.gov), and [FoodSafety.gov](http://www.FoodSafety.gov); (2) car safety recalls from the [National Highway Traffic Safety Administration](http://www.nhtsa.gov); and (3) product safety recalls from the [Consumer Product Safety Commission](http://www.cpsc.gov).

<a name="what-it-returns"></a><h2>What it Returns</h2>

Below are three sample JSON responses for food, product, and car safety recalls.

### Food Recalls

	{"success":{
	    "total":2,
	    "results":[
	        {
	            "organization":"FDA",
	            "recall_number":"b6d9527fc7",
	            "recall_date":"2012-12-18",
	            "recall_url":"http://www.fda.gov/Safety/Recalls/ucm332784.htm",
	            "description":"True Taste, LLC of Kenosha, WI, is recalling it's vacuum packaged Hot Smoked Rainbow Trout",
	            "summary":"True Taste, LLC RECALLS,  \"Hot Smoked Rainbow Trout\""
	        },	
	        {
	            "organization":"FDA",
	            "recall_number":"8e54d46b8d",
	            "recall_date":"2012-12-18",
	            "recall_url":"http://www.fda.gov/Safety/Recalls/ucm332787.htm",
	            "description":"Matrixx Initiatives is voluntarily recalling 1 lot of Zicam&reg;",
	            "summary":"Matrixx Initiatives Issues Nationwide Voluntary Recall of One Lot of Zicam&reg;"
	        }
	    ]
	}}

### Product Recalls

	{"success":{
	    "total":2,
	    "results":[
	        {
	            "organization":"CPSC",
	            "recall_number":"12080",
	            "recall_date":"2012-01-05",
	            "recall_url":"http://www.cpsc.gov/cpscpub/prerel/prhtml12/12080.html",
	            "manufacturers":["Target"],
	            "product_types":["Lights & Accessories"],
	            "descriptions":["Target 6-pc. LED Flashlight Sets"],
	            "upcs":["490021010049"],
	            "hazards":["Fire & Fire-Related Burn"],
	            "countries":["China"]
	        },<commit_msg>Updated recalls API examples<commit_after>---
permalink: /developer/recalls.html
layout: post
title: Recalls API
tags: recalls api
---

[USASearch](http://usasearch.howto.gov) > [APIs for Developers](/developer/index.html) > Recalls API

<a href="https://github.com/GSA-OCSIT"><img style="position: absolute; top: 41px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>

Helping alert the public to unsafe, hazardous, or defective products.

<ul>
  <li class="overview current"><a href="#overview">Overview</a></li>
  <li class="api"><a href="#using-the-api">Using the API</a></li>
  <li class="parameters"><a href="#parameters">Parameters</a></li>
  <li class="sources"><a href="#data-sources">Data Sources</a></li>
  <li class="returns"><a href="#what-it-returns">What it Returns</a></li>
</ul>

<a name="overview"></a><h2>Overview</h2>

When you're buying and using products, safety comes first.

Six federal regulatory agencies issue recalls on [Recalls.gov](http://www.recalls.gov).

This Recalls API allows you to tap into a list of (1) drug and food safety recalls from the [Food and Drug Administration](http://www.fda.gov), [Food Safety and Inspection Service](http://www.fsis.usda.gov), and [FoodSafety.gov](http://www.FoodSafety.gov); (2) car safety recalls from the [National Highway Traffic Safety Administration](http://www.nhtsa.gov); and (3) product safety recalls from the [Consumer Product Safety Commission](http://www.cpsc.gov).

This API is great for consumer safety websites or applications, news organizations, and websites or magazines targeted to specific audiences, such as parents.

<a name="using-the-api"></a><h2>Using the API</h2>

This Recalls API accepts a GET request.

Recalls are searchable by keyword, issuing agency, date, UPC code, vehicle-specific attributes, or any combination of these.

The base URL is http://api.usa.gov/recalls/search.json?**parameter**

Sample API requests follow.

All recalls  
<http://api.usa.gov/recalls/search.json?>

All cribs  
<http://api.usa.gov/recalls/search.json?query=cribs>

All cribs that pose a choking hazard  
<http://api.usa.gov/recalls/search.json?query=cribs+choking>


All cribs that pose a choking hazard sorted by date  
<http://api.usa.gov/recalls/search.json?query=cribs+choking&sort=date>

<a name="parameters"></a><h2>Parameters</h2>

Seven generic parameters are accepted: (1) `query`, (2) `organization`, (3) `start_date`, (4) `end_date`, (5) `page`, (6) `per_page`, and (7) `sort`. There are additional parameters that are specific to food, product, and car safety recalls. None are required.

### query

Attempts to extract as much "signal" as possible from the input text. Handles word variants, so a search on "choke" will find a recall categorized as a "choking" hazard.

### organization

Specifies which agency issued the recall. Possible values are `CPSC`, `FDA`, `NHTSA`, or `USDA`.

Example (one agency): <http://api.usa.gov/recalls/search.json?organization=nhtsa>

Example (multiple agencies): <http://api.usa.gov/recalls/search.json?organization=fda+usda>

### start_date

Specifies the start date of the recall.

Example: <http://api.usa.gov/recalls/search.json?start_date=2012-01-01>

### end_date

Specifies the end date of the recall.

Example: <http://api.usa.gov/recalls/search.json?end_date=2012-12-31>

### page

Specifies the pagination of search results. Possible values are `1` to `20`.

Example: <http://api.usa.gov/recalls/search.json?page=3>

### per_page

Specifies the number of search results for each page. Possible values are `1` to `50`.

Example: <http://api.usa.gov/recalls/search.json?per_page=10>

### sort

Results are sorted by relevance by default. Possible values are `rel` or `date`. Use 'sort=date' to sort results by date with the most recent listed first.

Example: <http://api.usa.gov/recalls/search.json?sort=date>

### food_type 
Only for drug and food safety recalls. Possible values are `food` or `drug`.

Example: <http://api.usa.gov/recalls/search.json?food_type=drug>

### upc

Only for CPSC recalls. Specifies the UPC code when available. Not all products have UPC codes.

Example: <http://api.usa.gov/recalls/search.json?upc=042666601627>

### make, model, year, and code (only for NHTSA recalls)

* `make` specifies the make of the vehicle or equipment. Example: <http://localhost:3000/search?make=winnebago>
* `model` specifies the model of the vehicle or equipment. Example: <http://localhost:3000/search?model=ellipse>
* `year` specifies the year of the vehicle or equipment. Example: <http://localhost:3000/search?year=2010>
* `code` specifies the NHTSA code. Possible values are `E`, `V` [for vehicles], `I`, `T`, `C`, or `X`. Example: <http://localhost:3000/search?code=v>

<a name="data-sources"></a><h2>Data Sources</h2>

Data are normalized across (1) drug and food safety recalls from the [Food and Drug Administration](http://www.fda.gov), [Food Safety and Inspection Service](http://www.fsis.usda.gov), and [FoodSafety.gov](http://www.FoodSafety.gov); (2) car safety recalls from the [National Highway Traffic Safety Administration](http://www.nhtsa.gov); and (3) product safety recalls from the [Consumer Product Safety Commission](http://www.cpsc.gov).

<a name="what-it-returns"></a><h2>What it Returns</h2>

Below are three sample JSON responses for food, product, and car safety recalls.

### Food Recalls

	{
		success: {
			total: 82,
			results: [
				{
					organization: "USDA",
					recall_number: "1df0a5440b",
					recall_date: "2011-05-14",
					recall_url: "http://www.fsis.usda.gov/News_&_Events/Recall_037_2011_Release/index.asp",
					description: "Rose & Shore Meat Co., a Vernon, Calif., establishment, is recalling approximately 15,900 pounds of ready-to-eat deli meat products that may be contaminated with Listeria monocytogenes.",
					summary: "California Firm Recalls Deli Meat Products for Possible Listeria Contamination"
				},
				{
					organization: "FDA",
					recall_number: "51d9096a25",
					recall_date: "2010-06-21",
					recall_url: "http://www.fda.gov/Safety/Recalls/ucm216371.htm",
					description: "Portland Shellfish Company, Inc. is expanding this voluntarily recall to include the Meat Without Feet private label food service (2 Lb bags), pack of ready to eat frozen lobster claw and knuckle meat. Lot 13310, as recent tests show the product has the potential to be contaminated with Listeria monocytogenes, an organism which can cause serious and sometimes fatal infections in young children, frail or elderly people, and others with weakened immune systems",
					summary: "Portland Shellfish Company Expands Recall to Include Meat Without Feet Label, Lobster Claw and Knuckle Meat, because of Possible Health Risk"
				}
		    ]
	}}

### Product Recalls

	{"success":{
	    "total":2,
	    "results":[
	        {
	            "organization":"CPSC",
	            "recall_number":"12080",
	            "recall_date":"2012-01-05",
	            "recall_url":"http://www.cpsc.gov/cpscpub/prerel/prhtml12/12080.html",
	            "manufacturers":["Target"],
	            "product_types":["Lights & Accessories"],
	            "descriptions":["Target 6-pc. LED Flashlight Sets"],
	            "upcs":["490021010049"],
	            "hazards":["Fire & Fire-Related Burn"],
	            "countries":["China"]
	        },
{'fraction_non_alphanumeric': 0.14168880190130015, 'fraction_numerical': 0.024045854886061792, 'mean_word_length': 4.1023537803138375, 'pattern_counts': {'":': 41, '<': 127, '<?xml version=': 0, '>': 131, 'https://': 4, 'lorem ipsum': 0, 'www.': 28, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4603626', 'n_tokens_mistral': 4929, 'n_tokens_neox': 4394, 'n_words': 1370}