# Data dictionary: `data/recalls.json` and `data/recalls.csv`

One record per CPSC recall notice. **Counts are of notices, not products**: one notice can cover many products and thousands of units.

Fields marked **CPSC** are copied from CPSC's feed (text cleaned of HTML). Fields marked **Rule** are worked out by this site's rules (`scripts/build_insights.py`) and are not stated by CPSC. Rule fields are lower bounds: they can miss unusual wording.

| Field | Type | Source | Meaning |
|---|---|---|---|
| `recall_number` | text | CPSC | CPSC's recall number, unique. Used in the page address `/recalls/<number>`. |
| `recall_date` | date `YYYY-MM-DD` | CPSC | The date CPSC puts on the notice. Not when the product was sold or the hazard found. |
| `title` | text | CPSC | The notice headline. |
| `notice_url` | URL | CPSC | The official CPSC notice. Cite this. Two links in CPSC's feed were malformed (`hhttps://`, `https:/www`) and are repaired here. |
| `page_url` | URL | Site | This site's page for the recall. |
| `products[]` | list | CPSC | `name`, `model`, `type`, and `units_text` (the units sentence as written, for example "About 1.5 million"). |
| `manufacturers`, `importers`, `distributors` | lists of text | CPSC | Company names as CPSC wrote them (with place names). Not standardised: the same company can appear under several spellings. |
| `manufacturer_countries` | list of text | CPSC | Countries where the product was made. Near-complete since about 2004; sparse before. |
| `hazard_text` | text | CPSC | Why the product was recalled. |
| `description` | text | CPSC | Product description. |
| `injury_text` | text | CPSC | Incidents and injuries reported when the notice was written. "None reported" means none had been reported then. |
| `sold_at_text` | text | CPSC | Where and when it was sold, and the price, as one or two sentences. Present for nearly every recall since 2000. |
| `remedy_options` | list | CPSC | Any of Refund, Repair, Replace. Filled in for nearly every recall since 2012, none before 2010. |
| `remedy_text` | text | CPSC | What consumers should do. |
| `images[]` | list | CPSC | `url` (spaces encoded) and `caption`. Mostly product photos; some are diagrams or labels. First image in 1998. |
| `consumer_contact` | text | CPSC | The firm's contact details. |
| `in_conjunction_urls` | list of URLs | CPSC | Links to related notices from Canadian or Mexican agencies. Filled unevenly: do not use as a share. |
| `last_published` | date | CPSC | CPSC's "last published" date. Clusters on website-update days, so it does not show corrections. |
| `derived.units_parsed` | integer or null | Rule | First number in the first product's `units_text`. Null when the text is in feet, pounds or similar. Low confidence. |
| `derived.price_up_to_usd` | number or null | Rule | Highest dollar amount in `sold_at_text`. Low confidence. |
| `derived.retailers_named` | list | Rule | Which of Amazon, Walmart, Target, Home Depot, Costco, Best Buy, Lowe's, eBay, Temu, Shein, AliExpress, TikTok Shop and Etsy the sold-at text names. |
| `derived.sold_online` | true or false | Rule | The sold-at text mentions a .com address, "online", "website", "e-commerce" or "internet". |
| `derived.hazard_tags` | list | Rule | Hazards whose key words appear in the headline or hazard text (fire and burns, choking, strangulation, suffocation, entrapment, tip-over, falls, cuts, lead, electric shock, magnets, drowning, carbon monoxide). A recall can have several. |
| `derived.refers_to_children` | true or false | Rule | The headline or hazard text mentions children, babies or similar. |
| `derived.injury_reported`, `derived.death_reported`, `derived.no_injury_reported` | true or false | Rule | Read from `injury_text`. Lower bounds. About 1 in 20 notices are unclear and are none of the three. |

## Using the data without misleading anyone

- Say "recall notices", not "products". Give the denominator.
- A share of recalls is not a share of products or sales.
- Read `insights.json` for statements that have been reviewed, and their do-not-say lists.
- The snapshot fingerprint and last-checked date are in `meta`.