FDA Food Recalls Scraper - openFDA Enforcement API

Scrape FDA food recalls and enforcement reports straight from the official openFDA API, with no API key and no rate-limit setup on your side. Get clean, structured food recall data for compliance monitoring, food-safety alerts, retail and supplier risk checks, and research. This is the most complete openFDA food recall scraper on Apify: it returns every field the FDA food enforcement database exposes, adds derived fields for faster analysis, and gives you keyword, hazard-class, firm, product, geography and date filters.

Here is one real result, with every field the actor returns:

{
  "recallNumber": "F-0609-2015",
  "status": "Terminated",
  "classification": "Class I",
  "productType": "Food",
  "productDescription": "Crema GuateLinda (Guatemalan Style Cream) in individually soft poly/plastic bags labeled in part: Lacteos Santa Martha Crema GuateLinda Guatemalan Style Cream Net WT 1 LB (16 oz)",
  "reasonForRecall": "Listeria monocytogenes found in environmental and finished-product samples. Firm is voluntarily recalling all brand products within expiration date.",
  "recallingFirm": "Oasis Brands, Inc",
  "city": "Miami",
  "state": "FL",
  "country": "United States",
  "postalCode": "33182",
  "addressLine1": "13439 NW 19 LANE",
  "addressLine2": null,
  "distributionPattern": "FL, GA. NC, and TN",
  "productQuantity": "144 pieces",
  "codeInfo": "UPC 635349 000390  Best By dates: 07/01/14 thru 12/31/14",
  "moreCodeInfo": null,
  "voluntaryMandated": "Voluntary: Firm initiated",
  "initialFirmNotification": "Two or more of the following: Email, Fax, Letter, Press Release, Telephone, Visit",
  "recallInitiationDate": "2014-10-10",
  "centerClassificationDate": "2014-12-02",
  "reportDate": "2014-12-10",
  "terminationDate": "2017-03-28",
  "eventId": "69516",
  "classificationLevel": 1,
  "active": false,
  "firmAddress": "13439 NW 19 LANE, Miami, FL 33182, United States",
  "recallAgeDays": 4261,
  "distributionNationwide": false,
  "distributionStates": ["FL", "GA", "NC", "TN"],
  "riskScore": 68,
  "openfda": null,
  "sourceApiUrl": "https://api.fda.gov/food/enforcement.json?search=recall_number:%22F-0609-2015%22",
  "firmRecallHistory": null,
  "observedAt": "2026-08-10T14:05:09.001Z",
  "error": null
}

📥 Input · 📤 Output · 💰 Pricing · ▶️ Examples

Table of contents

• What it does
• Use cases
• Quickstart
• Compare to other FDA recall scrapers
• Input reference
• Firm recall history add-on
• Output reference
• Example output record
• Run via API and CLI
• Fetch results
• Billing and limits
• FAQ and troubleshooting

What it does

The actor calls the openFDA food enforcement dataset (/food/enforcement.json), applies the filters you pass as input, paginates through the matching recalls, and writes one normalized record per recall to the run's dataset. Dates that the FDA stores as YYYYMMDD strings are parsed to ISO YYYY-MM-DD, missing source values are returned as honest null (never invented), and a set of derived fields (riskScore, distributionStates, distributionNationwide, firmAddress, recallAgeDays, classificationLevel, active, sourceApiUrl) is computed on top of the raw FDA fields so you can sort and filter without extra parsing.

Data covers US food recalls only (product_type = Food). It does not include drug or device recalls (see the openFDA Drug Events & Recalls Scraper for drugs). The source is a public government API, so no browser and no proxy are needed.

Use cases

• Food-safety and recall monitoring. Track new Class I recalls, listeria, salmonella, E. coli, or undeclared allergen recalls as they are reported.
• Compliance and supplier risk. Screen your suppliers and co-manufacturers against their FDA recall track record with the firm recall history add-on.
• Retail and grocery. Match recalled products, lot codes and UPCs against your catalog.
• Insurance, legal and research. Build a structured food recall dataset with reasons, distribution scope and dates for analysis.
• Alerting and dashboards. Schedule the actor and feed the JSON into your own alerting, BI or spreadsheet workflow.

Quickstart

Open the actor, paste this into the input, and press Run. It returns the 10 most recent listeria food recalls.

{
  "maxRecalls": 10,
  "searchQuery": "listeria",
  "dateField": "report_date",
  "sortOrder": "Newest first"
}

Leave searchQuery empty to pull the most recent food recalls with no keyword filter. Every input field is optional; with an empty input the actor returns the most recent food recalls (default maxRecalls is 10 on free plans).

Compare to other FDA recall scrapers

Capability	This actor	automation-lab/fda-food-recalls	parseforge/reapx openFDA (generic)
No API key required	Yes	Yes	Yes
Keyword search (reason + product)	Yes	Yes	Partial (raw expression only)
Single filters (class, status, state, country, firm, city, product)	Yes	Yes	No
Multi-value filters (classifications, statuses, states, countries, productKeywords)	Yes	Yes (arrays)	No
Recall number and event ID lookup	Yes	No	No
Report date and initiation date ranges	Yes	Yes	Partial (ignored for food)
Sort by any of 4 date fields	Yes	Report / initiation only	No
Firm postal address fields	Yes (lines + single line)	Yes (single)	Raw only
Derived risk score, distribution states, recall age	Yes	No	No
openFDA API source URL per record	Yes	Yes	No
Firm recall history add-on (per-firm track record)	Yes	No	No
Per-result price	From $0.008	Comparable	$0.021

This actor accepts every input the dedicated food-recall competitor accepts (their array field names are supported as aliases) and returns every output they return, plus recall-number and event-ID lookup, four sortable date fields, derived analytics fields, and the firm recall history add-on. Against the generic multi-endpoint openFDA scrapers, it adds real food-specific filtering instead of raw expressions only, at a lower per-result price.

Input reference

All fields are optional. Single-value filters combine with logical AND. Multi-value filters match any of the listed values (logical OR) and then AND with the rest.

Field	Type	Default	Description
maxRecalls	integer	10	Maximum records to collect. Aliases: maxItems, maxResults, maxRecords. openFDA paginates with a skip offset up to 25000 per query; for larger pulls, narrow the filters or date range.
searchQuery	string	(empty)	A plain keyword matched against reason_for_recall (for example listeria, salmonella, undeclared allergen), OR a raw openFDA field expression such as product_description:cheese. Alias: query.
classification	enum	(any)	Hazard class: Class I, Class II, Class III. Class I is most serious.
status	enum	(any)	Recall status: Ongoing, Completed, Terminated, Pending.
state	enum	(any)	Two-letter US state code of the recalling firm, for example CA, NY, TX.
recallingFirm	string	(empty)	Firm or manufacturer name phrase, for example Tyson, Dole, Nestle.
productDescription	string	(empty)	Word or phrase in the product description, for example cheese, spinach, peanut butter.
city	string	(empty)	City of the recalling firm, for example Los Angeles.
country	string	(empty)	Country of the recalling firm, for example United States, Canada.
voluntaryMandated	enum	(any)	Voluntary (firm initiated) or Mandated (FDA ordered).
dateFrom / dateTo	string	(empty)	Include recalls on or after / on or before this date (YYYY-MM-DD). Applies to dateField.
dateField	enum	report_date	Which date the dateFrom/dateTo range applies to: report_date, recall_initiation_date, center_classification_date, termination_date. Alias: sortBy.
sortOrder	enum	(relevance)	Newest first or Oldest first, ordered on dateField. Aliases: sortDirection = asc / desc.
recallNumber	string	(empty)	Look up one exact FDA recall number, for example F-0609-2015.
eventId	string	(empty)	Pull every recall in one FDA recall event, for example 69516.
productKeywords	string[]	(empty)	Match any keyword in the product description or recall reason, for example ["cheese", "spinach"].
classifications	string[]	(empty)	Match any of these hazard classes, for example ["Class I", "Class II"].
statuses	string[]	(empty)	Match any of these recall statuses.
states	string[]	(empty)	Match any of these two-letter state codes.
countries	string[]	(empty)	Match any of these recalling-firm countries.
reportDateFrom / reportDateTo	string	(empty)	FDA report date range (YYYY-MM-DD), independent of dateField.
initiationDateFrom / initiationDateTo	string	(empty)	Recall initiation date range (YYYY-MM-DD).
includeFirmHistory	boolean	false	Paid add-on. Add a firmRecallHistory object per row. See below.
proxyConfiguration	object	(none)	Standard Apify proxy configuration. Not required; the source is not bot protected.

If you pass no filters at all, the actor defaults to product_type:Food so you get food recalls only.

Firm recall history add-on

Set includeFirmHistory to true (paying plans only) to attach a firmRecallHistory object to each row. For every unique recalling firm in your results, the actor aggregates that firm's full openFDA food-recall track record so you can gauge supplier risk at a glance:

"firmRecallHistory": {
  "firm": "Oasis Brands, Inc",
  "totalRecalls": 17,
  "classI": 17,
  "classII": 0,
  "classIII": 0,
  "statusBreakdown": { "Terminated": 17 },
  "earliestReportDate": "2014-09-10",
  "latestReportDate": "2014-12-10"
}

The add-on is billed as the details event, and only for rows that actually receive firm-history data, charged after the base result row is delivered within your spend cap. Firm lookups are cached, so repeated firms cost no extra work. Leave the option off for the standard per-result export at no add-on cost.

Output reference

One dataset item per recall. Types: string, integer, boolean, string[], object, or null when the source value is absent.

Field	Type	Description
recallNumber	string	FDA recall number (unique per recall), for example F-0609-2015.
status	string	Recall status: Ongoing, Completed, Terminated, or Pending.
classification	string	Hazard class: Class I, Class II, or Class III.
productType	string	Product type. Always Food for this actor.
productDescription	string	Full labeled description of the recalled product.
reasonForRecall	string	Narrative reason the product was recalled.
recallingFirm	string	Firm or manufacturer that initiated or is subject to the recall.
city	string	City of the recalling firm.
state	string	Two-letter state code of the recalling firm.
country	string	Country of the recalling firm.
postalCode	string	Postal code of the recalling firm.
addressLine1	string	First line of the firm street address.
addressLine2	string	Second line of the firm street address, or null.
distributionPattern	string	Free-text description of where the product was distributed.
productQuantity	string	Quantity of product in distribution.
codeInfo	string	Lot codes, UPCs, best-by dates identifying affected product.
moreCodeInfo	string	Additional code information, or null.
voluntaryMandated	string	Whether the recall was firm initiated (voluntary) or FDA mandated.
initialFirmNotification	string	How the firm first notified the public or trade.
recallInitiationDate	string	Date the firm started the recall (YYYY-MM-DD).
centerClassificationDate	string	Date the FDA center classified the recall (YYYY-MM-DD).
reportDate	string	Date the recall was first reported by the FDA (YYYY-MM-DD).
terminationDate	string	Date the recall was terminated (YYYY-MM-DD), or null if still open.
eventId	string	FDA event ID grouping related recalls.
classificationLevel	integer	Numeric hazard rank: 1 = Class I, 2 = Class II, 3 = Class III, null if unknown.
active	boolean	true while the recall is Ongoing or Pending, otherwise false.
firmAddress	string	Single-line firm postal address, ready for CRM or mapping.
recallAgeDays	integer	Whole days between reportDate and the run time.
distributionNationwide	boolean	true when the distribution text names nationwide or all-states distribution.
distributionStates	string[]	US state codes parsed from distributionPattern. Empty array when none are named.
riskScore	integer	Composite 0 to 100 hazard score combining severity, recency, and distribution scope. Higher is more urgent. null if severity is unknown.
openfda	object	The openFDA harmonization block when present, otherwise null.
sourceApiUrl	string	Deterministic openFDA API URL for this exact recall record.
firmRecallHistory	object	Firm recall track record (paid add-on), or null when the add-on is off.
observedAt	string	ISO 8601 timestamp of when the record was collected.
error	string	null on success. On a failed run, a single item with a populated error field is written instead.

Derived field notes

• riskScore weighting: severity is the dominant component (Class I = 60, II = 40, III = 20), plus up to +20 for recency (fading over about 6 years), plus up to +20 for distribution scope (nationwide = +20, otherwise +2 per affected state, capped).
• distributionStates parses full state names and standalone two-letter codes from the free-text distributionPattern. Nationwide or international text yields an empty array.

Example output record

Real record from a live run (input {"searchQuery": "listeria", "maxRecalls": 10}). See the JSON at the top of this page for the full field list.

Run via API and CLI

Start a run and wait for it to finish, then read the dataset. Replace <TOKEN> with your Apify API token.

Run synchronously and get dataset items in one call:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~openfda-food-recalls-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchQuery":"listeria","classifications":["Class I","Class II"],"states":["CA","NY"],"maxRecalls":25,"sortOrder":"Newest first"}'

Start a run asynchronously:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~openfda-food-recalls-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"productKeywords":["peanut butter","almond"],"reportDateFrom":"2024-01-01","maxRecalls":100}'

Apify CLI:

apify call scrapers_lat/openfda-food-recalls-scraper \
  --input '{"eventId":"69516"}'

Fetch results

Every run writes to a dataset. Fetch items as JSON, CSV, or Excel by changing format:

# JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

# CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

# Paginate large datasets
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"

<DATASET_ID> is returned as defaultDatasetId in the run object. Use offset and limit to page through large result sets. clean=true drops empty and internal fields.

Billing and limits

• Pay per result. You are charged per record returned (result event). See the pricing tab for the current per-result price.
• Firm history add-on. When includeFirmHistory is on (paying plans), rows that receive firm-history data are additionally charged the details event. Rows without firm data are not charged the add-on.
• No charge on failure. If a run errors, the actor writes a single item with a populated error field and does not charge for it. Empty runs cost nothing.
• Spend cap respected. Set maxTotalChargeUsd on the run; once reached, the actor stops emitting and charging further billable results and add-ons.
• Free Apify plans are capped at 10 records per run. Upgrade for higher maxRecalls.
• Source pagination ceiling. openFDA allows a skip offset up to 25000 per query. For pulls beyond that, split the work with narrower filters or date ranges. Without a key the API also limits request volume, so very large pulls are paced.

FAQ and troubleshooting

Do I need an FDA or openFDA API key? No. The actor uses the public keyless openFDA tier. You only need an Apify account.

A run returned 0 records. Why? The filter combination matched nothing in the source. Loosen filters (for example remove state or widen the date range), or confirm the keyword exists in reason_for_recall. Zero-result runs are not charged.

How do I get only the most serious recalls? Set classification to Class I, or pass classifications: ["Class I"]. Combine with a keyword such as listeria and optionally a state code.

What is the difference between searchQuery keyword mode and raw mode? A plain word (for example listeria) is matched against the recall reason. A value containing field: (for example product_description:cheese) is passed through as a raw openFDA search expression against that field.

Why is terminationDate null? The recall is still open (Ongoing or Pending) so the FDA has not set a termination date. Missing source values are returned as null, never invented.

Can I pull all recalls for one incident? Yes. Pass the eventId. A single FDA event often groups many related product recalls.

What does the firm recall history add-on cost? It is billed as the details event, only for rows that receive firm data, and only on paying plans. See the pricing tab.

Is this an official FDA tool? No. This actor is independent and has no affiliation with the FDA or openFDA. It reads only data that is publicly available through the openFDA API. Use it in accordance with the openFDA terms of service.

Example tasks

Preconfigured templates for common scenarios. Open one and press Run, or use it as a starting point:

• openFDA Dietary Supplement Recalls
• openFDA E. coli Food Recalls
• openFDA Foreign Material Food Recalls
• openFDA Ice Cream Recalls
• openFDA Infant Formula Recalls
• openFDA Undeclared Milk Allergen Recalls
• openFDA Undeclared Peanut Allergen Recalls
• Find Class I Allergen Food Recalls
• Track Listeria Food Recalls
• Monitor Salmonella Food Recalls

Related scrapers

• openFDA Drug Events & Recalls Scraper: FDA drug adverse events (FAERS) and drug recalls.
• SEC EDGAR Company Filings Scraper: SEC filings by ticker or CIK.
• USAspending Federal Award Scraper: US federal prime awards.
• OFAC Sanctions List Scraper: US Treasury OFAC SDN and Consolidated lists.
• Grants.gov Opportunity Scraper: US federal grant opportunities.
• Federal Register Document Scraper: US Federal Register documents.

More scrapers at scrapers.lat

Built and maintained by scrapers.lat, where we publish scrapers for US and Latin American public platforms: company registries, government data, finance, e-commerce and more. Browse the catalog or request a custom scraper at scrapers.lat.

Independent tool, not affiliated with the FDA or openFDA. Accesses only publicly available openFDA data. Use in accordance with the openFDA terms of service.

---

FDA Food Recalls Scraper - openFDA Enforcement API (Espanol)

Extrae retiros de alimentos y reportes de cumplimiento de la FDA directamente de la API oficial openFDA, sin clave de API y sin que tengas que configurar limites de peticiones. Obten datos de retiros de alimentos limpios y estructurados para monitoreo de cumplimiento, alertas de seguridad alimentaria, verificacion de riesgo de proveedores y comercio minorista, e investigacion. Es el scraper de retiros de alimentos openFDA mas completo de Apify: devuelve todos los campos que expone la base de datos de cumplimiento alimentario de la FDA, agrega campos derivados para un analisis mas rapido, y te ofrece filtros por palabra clave, clase de peligro, empresa, producto, geografia y fechas.

Arriba, en la seccion en ingles, se muestra un resultado real con todos los campos que devuelve el actor.

Que hace

El actor consulta el conjunto de datos de cumplimiento alimentario de openFDA (/food/enforcement.json), aplica los filtros que envias como entrada, pagina los retiros que coinciden y escribe un registro normalizado por retiro en el dataset de la ejecucion. Las fechas que la FDA almacena como texto YYYYMMDD se convierten a ISO YYYY-MM-DD, los valores ausentes se devuelven como null honesto (nunca se inventan) y se calcula un conjunto de campos derivados (riskScore, distributionStates, distributionNationwide, firmAddress, recallAgeDays, classificationLevel, active, sourceApiUrl) sobre los campos originales de la FDA para que puedas ordenar y filtrar sin procesamiento adicional.

Los datos cubren solo retiros de alimentos de EE. UU. (product_type = Food). No incluye retiros de medicamentos ni dispositivos (consulta el openFDA Drug Events & Recalls Scraper para medicamentos). La fuente es una API publica del gobierno, por lo que no se necesita navegador ni proxy.

Casos de uso

• Monitoreo de seguridad alimentaria y retiros. Sigue nuevos retiros Clase I, listeria, salmonella, E. coli o alergenos no declarados en cuanto se reportan.
• Cumplimiento y riesgo de proveedores. Evalua a tus proveedores y co-fabricantes con su historial de retiros de la FDA usando el complemento de historial de la empresa.
• Comercio minorista y supermercados. Cruza productos retirados, codigos de lote y UPC contra tu catalogo.
• Seguros, legal e investigacion. Construye un conjunto de datos estructurado de retiros con motivos, alcance de distribucion y fechas.
• Alertas y tableros. Programa el actor y alimenta el JSON en tu flujo de alertas, BI o hoja de calculo.

Inicio rapido

Abre el actor, pega esto en la entrada y presiona Run. Devuelve los 10 retiros de alimentos por listeria mas recientes.

{
  "maxRecalls": 10,
  "searchQuery": "listeria",
  "dateField": "report_date",
  "sortOrder": "Newest first"
}

Deja searchQuery vacio para obtener los retiros de alimentos mas recientes sin filtro de palabra clave. Todos los campos de entrada son opcionales; con una entrada vacia el actor devuelve los retiros mas recientes (el valor por defecto de maxRecalls es 10 en planes gratuitos).

Comparacion con otros scrapers de retiros de la FDA

Capacidad	Este actor	automation-lab/fda-food-recalls	parseforge/reapx openFDA (generico)
No requiere clave de API	Si	Si	Si
Busqueda por palabra clave (motivo + producto)	Si	Si	Parcial (solo expresion cruda)
Filtros simples (clase, estado, pais, empresa, ciudad, producto)	Si	Si	No
Filtros multivalor (clasificaciones, estados, paises, palabras clave)	Si	Si (arreglos)	No
Busqueda por numero de retiro y ID de evento	Si	No	No
Rangos de fecha de reporte e inicio	Si	Si	Parcial (ignorado en alimentos)
Ordenar por cualquiera de 4 campos de fecha	Si	Solo reporte / inicio	No
Campos de direccion postal de la empresa	Si (lineas + linea unica)	Si (unica)	Solo cruda
Puntaje de riesgo, estados de distribucion, antiguedad	Si	No	No
URL de la API openFDA por registro	Si	Si	No
Complemento de historial de retiros de la empresa	Si	No	No
Precio por resultado	Desde $0.008	Comparable	$0.021

Este actor acepta toda entrada que acepta el competidor dedicado de retiros de alimentos (los nombres de sus campos de arreglo se admiten como alias) y devuelve toda salida que ellos devuelven, ademas de busqueda por numero de retiro e ID de evento, cuatro campos de fecha ordenables, campos analiticos derivados y el complemento de historial de retiros de la empresa. Frente a los scrapers openFDA genericos multi-endpoint, agrega filtrado real especifico de alimentos en lugar de solo expresiones crudas, a un precio por resultado menor.

Referencia de entradas

Todos los campos son opcionales. Los filtros de valor unico se combinan con AND logico. Los filtros multivalor coinciden con cualquiera de los valores indicados (OR logico) y luego se combinan con el resto mediante AND.

Campo	Tipo	Por defecto	Descripcion
maxRecalls	integer	10	Maximo de registros a recolectar. Alias: maxItems, maxResults, maxRecords. openFDA pagina con un desplazamiento skip de hasta 25000 por consulta; para extracciones mayores, acota los filtros o el rango de fechas.
searchQuery	string	(vacio)	Palabra clave simple comparada con reason_for_recall (por ejemplo listeria, salmonella), O una expresion cruda de openFDA como product_description:cheese. Alias: query.
classification	enum	(cualquiera)	Clase de peligro: Class I, Class II, Class III. Clase I es la mas grave.
status	enum	(cualquiera)	Estado del retiro: Ongoing, Completed, Terminated, Pending.
state	enum	(cualquiera)	Codigo de estado de EE. UU. de dos letras de la empresa, por ejemplo CA, NY, TX.
recallingFirm	string	(vacio)	Nombre de la empresa o fabricante, por ejemplo Tyson, Dole, Nestle.
productDescription	string	(vacio)	Palabra o frase en la descripcion del producto, por ejemplo cheese, spinach.
city	string	(vacio)	Ciudad de la empresa, por ejemplo Los Angeles.
country	string	(vacio)	Pais de la empresa, por ejemplo United States, Canada.
voluntaryMandated	enum	(cualquiera)	Voluntary (iniciado por la empresa) o Mandated (ordenado por la FDA).
dateFrom / dateTo	string	(vacio)	Incluir retiros en o despues de / en o antes de esta fecha (YYYY-MM-DD). Se aplica a dateField.
dateField	enum	report_date	A que fecha se aplica el rango dateFrom/dateTo: report_date, recall_initiation_date, center_classification_date, termination_date. Alias: sortBy.
sortOrder	enum	(relevancia)	Newest first o Oldest first, ordenado por dateField. Alias: sortDirection = asc / desc.
recallNumber	string	(vacio)	Busca un numero de retiro exacto de la FDA, por ejemplo F-0609-2015.
eventId	string	(vacio)	Trae todos los retiros de un evento de la FDA, por ejemplo 69516.
productKeywords	string[]	(vacio)	Coincide con cualquier palabra clave en la descripcion o el motivo, por ejemplo ["cheese", "spinach"].
classifications	string[]	(vacio)	Coincide con cualquiera de estas clases de peligro.
statuses	string[]	(vacio)	Coincide con cualquiera de estos estados.
states	string[]	(vacio)	Coincide con cualquiera de estos codigos de estado.
countries	string[]	(vacio)	Coincide con cualquiera de estos paises.
reportDateFrom / reportDateTo	string	(vacio)	Rango de fecha de reporte de la FDA (YYYY-MM-DD).
initiationDateFrom / initiationDateTo	string	(vacio)	Rango de fecha de inicio del retiro (YYYY-MM-DD).
includeFirmHistory	boolean	false	Complemento de pago. Agrega un objeto firmRecallHistory por fila. Ver abajo.
proxyConfiguration	object	(ninguno)	Configuracion de proxy estandar de Apify. No es necesaria; la fuente no tiene proteccion antibot.

Si no pasas ningun filtro, el actor usa por defecto product_type:Food para devolver solo retiros de alimentos.

Complemento de historial de retiros de la empresa

Activa includeFirmHistory en true (solo planes de pago) para adjuntar un objeto firmRecallHistory a cada fila. Para cada empresa unica en tus resultados, el actor agrega el historial completo de retiros de alimentos de esa empresa en openFDA para que puedas evaluar el riesgo del proveedor de un vistazo:

"firmRecallHistory": {
  "firm": "Oasis Brands, Inc",
  "totalRecalls": 17,
  "classI": 17,
  "classII": 0,
  "classIII": 0,
  "statusBreakdown": { "Terminated": 17 },
  "earliestReportDate": "2014-09-10",
  "latestReportDate": "2014-12-10"
}

El complemento se factura como el evento details, y solo para las filas que realmente reciben datos de historial de empresa, cobrado despues de que la fila de resultado base se entrega dentro de tu limite de gasto. Las consultas por empresa se guardan en cache, asi que las empresas repetidas no cuestan trabajo adicional. Deja la opcion desactivada para la exportacion estandar por resultado sin costo de complemento.

Referencia de salida

Un elemento del dataset por retiro. Tipos: string, integer, boolean, string[], object, o null cuando el valor de origen no existe.

Campo	Tipo	Descripcion
recallNumber	string	Numero de retiro de la FDA (unico por retiro), por ejemplo F-0609-2015.
status	string	Estado del retiro: Ongoing, Completed, Terminated o Pending.
classification	string	Clase de peligro: Class I, Class II o Class III.
productType	string	Tipo de producto. Siempre Food en este actor.
productDescription	string	Descripcion etiquetada completa del producto retirado.
reasonForRecall	string	Motivo narrativo del retiro del producto.
recallingFirm	string	Empresa o fabricante que inicia o esta sujeto al retiro.
city	string	Ciudad de la empresa.
state	string	Codigo de estado de dos letras de la empresa.
country	string	Pais de la empresa.
postalCode	string	Codigo postal de la empresa.
addressLine1	string	Primera linea de la direccion de la empresa.
addressLine2	string	Segunda linea de la direccion, o null.
distributionPattern	string	Descripcion libre de donde se distribuyo el producto.
productQuantity	string	Cantidad de producto en distribucion.
codeInfo	string	Codigos de lote, UPC y fechas de consumo que identifican el producto afectado.
moreCodeInfo	string	Informacion de codigo adicional, o null.
voluntaryMandated	string	Si el retiro fue iniciado por la empresa (voluntario) u ordenado por la FDA.
initialFirmNotification	string	Como notifico la empresa por primera vez al publico o al comercio.
recallInitiationDate	string	Fecha en que la empresa inicio el retiro (YYYY-MM-DD).
centerClassificationDate	string	Fecha en que el centro de la FDA clasifico el retiro (YYYY-MM-DD).
reportDate	string	Fecha en que la FDA reporto por primera vez el retiro (YYYY-MM-DD).
terminationDate	string	Fecha en que se termino el retiro (YYYY-MM-DD), o null si sigue abierto.
eventId	string	ID de evento de la FDA que agrupa retiros relacionados.
classificationLevel	integer	Rango numerico de peligro: 1 = Clase I, 2 = Clase II, 3 = Clase III, null si se desconoce.
active	boolean	true mientras el retiro esta Ongoing o Pending, de lo contrario false.
firmAddress	string	Direccion postal de la empresa en una sola linea, lista para CRM o mapas.
recallAgeDays	integer	Dias completos entre reportDate y el momento de la ejecucion.
distributionNationwide	boolean	true cuando el texto de distribucion menciona distribucion nacional o en todos los estados.
distributionStates	string[]	Codigos de estado extraidos de distributionPattern. Arreglo vacio cuando no se nombran.
riskScore	integer	Puntaje compuesto de 0 a 100 que combina gravedad, actualidad y alcance de distribucion. Mayor es mas urgente. null si se desconoce la gravedad.
openfda	object	El bloque de armonizacion openFDA cuando esta presente, de lo contrario null.
sourceApiUrl	string	URL determinista de la API openFDA para este registro de retiro exacto.
firmRecallHistory	object	Historial de retiros de la empresa (complemento de pago), o null cuando el complemento esta desactivado.
observedAt	string	Marca de tiempo ISO 8601 de cuando se recolecto el registro.
error	string	null en caso de exito. En una ejecucion fallida, se escribe un unico elemento con un campo error poblado.

Notas de campos derivados

• Ponderacion de riskScore: la gravedad es el componente dominante (Clase I = 60, II = 40, III = 20), mas hasta +20 por actualidad (que se desvanece en unos 6 anos), mas hasta +20 por alcance de distribucion (nacional = +20, de lo contrario +2 por estado afectado, con tope).
• distributionStates analiza nombres completos de estados y codigos de dos letras del texto libre distributionPattern. El texto nacional o internacional produce un arreglo vacio.

Ejecutar via API y CLI

Inicia una ejecucion y espera a que termine, luego lee el dataset. Reemplaza <TOKEN> con tu token de API de Apify.

Ejecuta de forma sincrona y obten los elementos del dataset en una sola llamada:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~openfda-food-recalls-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchQuery":"listeria","classifications":["Class I","Class II"],"states":["CA","NY"],"maxRecalls":25,"sortOrder":"Newest first"}'

Inicia una ejecucion de forma asincrona:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~openfda-food-recalls-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"productKeywords":["peanut butter","almond"],"reportDateFrom":"2024-01-01","maxRecalls":100}'

CLI de Apify:

apify call scrapers_lat/openfda-food-recalls-scraper \
  --input '{"eventId":"69516"}'

Obtener resultados

Cada ejecucion escribe en un dataset. Obten los elementos como JSON, CSV o Excel cambiando format:

# JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

# CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

# Paginar datasets grandes
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"

<DATASET_ID> se devuelve como defaultDatasetId en el objeto de la ejecucion. Usa offset y limit para paginar. clean=true descarta campos vacios e internos.

Facturacion y limites

• Pago por resultado. Se te cobra por registro devuelto (evento result). Consulta la pestana de precios para el precio actual por resultado.
• Complemento de historial de empresa. Cuando includeFirmHistory esta activo (planes de pago), las filas que reciben datos de historial se cobran adicionalmente con el evento details. Las filas sin datos de empresa no pagan el complemento.
• Sin cargo en caso de fallo. Si una ejecucion falla, el actor escribe un unico elemento con un campo error y no cobra por el. Las ejecuciones vacias no cuestan nada.
• Se respeta el limite de gasto. Configura maxTotalChargeUsd en la ejecucion; al alcanzarlo, el actor deja de emitir y cobrar mas resultados y complementos.
• Los planes gratuitos de Apify tienen un tope de 10 registros por ejecucion. Actualiza para un maxRecalls mayor.
• Tope de paginacion de origen. openFDA permite un desplazamiento skip de hasta 25000 por consulta. Para extracciones mayores, divide el trabajo con filtros o rangos de fecha mas estrechos. Sin clave, la API tambien limita el volumen de peticiones, asi que las extracciones muy grandes van a un ritmo controlado.

Preguntas frecuentes

Necesito una clave de API de la FDA u openFDA? No. El actor usa el nivel publico sin clave de openFDA. Solo necesitas una cuenta de Apify.

Una ejecucion devolvio 0 registros. Por que? La combinacion de filtros no coincidio con nada en la fuente. Relaja los filtros o confirma que la palabra clave existe en reason_for_recall. Las ejecuciones con cero resultados no se cobran.

Como obtengo solo los retiros mas graves? Configura classification en Class I, o pasa classifications: ["Class I"]. Combina con una palabra clave como listeria y opcionalmente un codigo de state.

Cual es la diferencia entre el modo palabra clave y el modo crudo de searchQuery? Una palabra simple (por ejemplo listeria) se compara con el motivo del retiro. Un valor que contiene field: (por ejemplo product_description:cheese) se pasa como expresion cruda de openFDA contra ese campo.

Por que es terminationDate null? El retiro sigue abierto (Ongoing o Pending), asi que la FDA no ha fijado fecha de terminacion. Los valores ausentes se devuelven como null, nunca inventados.

Puedo traer todos los retiros de un incidente? Si. Pasa el eventId. Un solo evento de la FDA suele agrupar muchos retiros de productos relacionados.

Cuanto cuesta el complemento de historial de retiros de la empresa? Se factura como el evento details, solo para las filas que reciben datos de empresa, y solo en planes de pago. Consulta la pestana de precios.

Es una herramienta oficial de la FDA? No. Este actor es independiente y no tiene afiliacion con la FDA ni con openFDA. Solo lee datos disponibles publicamente a traves de la API openFDA. Usalo conforme a los terminos de servicio de openFDA.