{ "openapi": "3.0.3", "info": { "title": "RecallTracker - Canadian Product & Vehicle Recall API", "description": "Canadian product and vehicle recall API. 41K+ records from Health Canada, CFIA, and Transport Canada. Food safety alerts, consumer product recalls, vehicle defects. Filter by recall_type, recall_agency, hazard_class, and allergen. Bilingual EN/FR. Updated every 15 minutes.", "version": "0.1.0" }, "paths": { "/health": { "get": { "summary": "Health", "operationId": "/health", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/recall/alerts/subscribe": { "post": { "summary": "Subscribe to email alerts for new recalls matching a saved search", "operationId": "/recall/alerts/subscribe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallAlertRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/alerts/unsubscribe": { "get": { "summary": "Unsubscribe from recall alerts", "operationId": "/recall/alerts/unsubscribe", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall": { "get": { "summary": "Search recalls", "operationId": "/recall", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Full-text search across data fields" }, { "name": "recall_type", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Recall type: food, vehicle, health_product, consumer_product, medical_device, cannabis" }, { "name": "recall_agency", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Recall issuing agency: CFIA, Health Canada, Transport Canada" }, { "name": "hazard_class", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Hazard class: class_1, class_2, class_3" }, { "name": "allergen", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter food recalls by allergen: milk, peanut, gluten, egg, fish, sesame, soy, sulphites, tree_nut, wheat, mustard, crustacean, shellfish" }, { "name": "issued_after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter by recall date >= YYYY-MM-DD (event_date)" }, { "name": "issued_before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter by date <= YYYY-MM-DD" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Sort field: date (recall date, default), published (recall date descending)" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: asc or desc", "default": "desc", "title": "Sort Order" }, "description": "Sort order: asc or desc" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Pagination cursor from next_cursor in a previous response. Use instead of offset for deep pagination." }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Return translations for a single language only: en or fr." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "entity_type": "recall", "count": 5, "next_cursor": "eyJkIjoiMjAyNS0wMy0xMiIsImkiOiI3NzQifQ==", "results": [ { "record_id": "77401", "recall_type": "food", "agency": "Health Canada", "hazard_class": "class_1", "event_date": "2025-03-12", "recalling_firm": "President's Choice", "allergens": [ "listeria" ], "translations": { "en": { "title": "President's Choice brand Spinach recalled due to Listeria", "hazard_description": "May be contaminated with Listeria monocytogenes.", "what_to_do": "Do not consume. Return to place of purchase." }, "fr": { "title": "Rappel des \u00e9pinards de marque President's Choice en raison de Listeria" } } } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/stats": { "get": { "summary": "Recall statistics", "operationId": "/recall/stats", "parameters": [ { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Data field to group by" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "description": "30d, 90d, 1y, all", "default": "30d", "title": "Period" }, "description": "30d, 90d, 1y, all" }, { "name": "sum_field", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Data field to sum (e.g. contract_value)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "entity_type": "recall", "period_days": 30, "total_in_db": 41474, "by_recall_type": [ { "value": "food", "count": 7200 }, { "value": "vehicle", "count": 17300 }, { "value": "consumer_product", "count": 12100 }, { "value": "health_product", "count": 3800 } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/products": { "get": { "summary": "Products and affected models for a recall", "operationId": "/recall/products", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "description": "recall_id from a recall record", "title": "Id" }, "description": "recall_id from a recall record" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "recall_id": "2024-076-HC", "recall_type": "health_product", "product_list": [ { "name": "Tylenol Extra Strength 500mg", "upc": "05631234567890" } ], "affected_models": null, "distribution": "National", "units_affected": null, "identification_number": "DIN 00559407", "manufacturer_recall_number": null, "system": null } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/upc": { "get": { "summary": "Product recalls matching a UPC or barcode", "operationId": "/recall/upc", "parameters": [ { "name": "upc", "in": "query", "required": true, "schema": { "type": "string", "description": "UPC, EAN, or GTIN barcode (digits only)", "title": "Upc" }, "description": "UPC, EAN, or GTIN barcode (digits only)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Language filter: en or fr" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "upc": "05631234567890", "digits": "05631234567890", "count": 1, "results": [ { "recall_id": "2024-076-HC", "recall_type": "health_product", "title_en": "Recall example" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/vin": { "get": { "summary": "Vehicle recalls matching a VIN", "operationId": "/recall/vin", "parameters": [ { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "description": "17-character Vehicle Identification Number", "title": "Vin" }, "description": "17-character Vehicle Identification Number" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Language filter: en or fr" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "vin": "1HGBH41JXMN109186", "decoded": { "make": "HONDA", "model": "ACCORD", "year": 2021 }, "count": 1, "results": [ { "recall_id": "2024-RC-001", "recall_type": "vehicle", "title_en": "Airbag inflator recall" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recall/{record_id}": { "get": { "summary": "Get recall by ID", "operationId": "/recall/{record_id}", "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Record Id" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Return translations for a single language only: en or fr." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "record_id": "77401", "recall_type": "food", "agency": "Health Canada", "hazard_class": "class_1", "event_date": "2025-03-12", "recalling_firm": "President's Choice", "allergens": [ "listeria" ], "translations": { "en": { "title": "President's Choice brand Spinach recalled due to Listeria", "hazard_description": "May be contaminated with Listeria monocytogenes.", "what_to_do": "Do not consume. Return to place of purchase." }, "fr": { "title": "Rappel des \u00e9pinards de marque President's Choice en raison de Listeria" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "RecallAlertRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "q": { "type": "string", "nullable": true }, "agency": { "type": "string", "nullable": true }, "recall_type": { "type": "string", "nullable": true }, "hazard_class": { "type": "string", "nullable": true }, "allergen": { "type": "string", "nullable": true } }, "type": "object", "required": [ "email" ], "title": "RecallAlertRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "servers": [ { "url": "https://hv1nforwhi.execute-api.ca-central-1.amazonaws.com" } ] }