UK Food Hygiene Rating Change Signals

This Actor compares complete official Food Standards Agency authority snapshots and emits one machine-readable business change per Dataset row. It reports changes rather than re-exporting the full food-business directory.

Official source and supported signals

It requests FSA API v2 authority metadata with x-api-version: 2, then downloads the authority's official daily XML FileName. No authentication, browser, or proxy is required.

Signals: RATING_DROPPED, RATING_IMPROVED, RATING_PENDING, RATING_PENDING_CLEARED, NEW_INSPECTION, NEW_BUSINESS, BUSINESS_REMOVED, BUSINESS_NAME_CHANGE, ADDRESS_CHANGE, and BUSINESS_TYPE_CHANGE.

FHRS numeric ratings compare 0–5. FHIS compares Improvement Required < Pass < Pass and Eat Safe. Exempt, awaiting-inspection, awaiting-publication, and unknown values are not ordinal. Numeric input filters apply only to FHRS and leave FHIS signals unaffected. Severity is a heuristic description of observed change, never a prediction.

Baseline, incremental state, and safety

The first successful run creates a baseline and emits no NEW_BUSINESS rows. baselineOnly: true cannot reset an existing baseline. localAuthorities accepts exact authority ID, code, or name and defines source scope; all other filters are output-only.

The named KVS uk-food-hygiene-rating-change-signals-state keeps a small scope CURRENT manifest referencing authority-partitioned generations and deterministic 2,000-record chunks. Unchanged LastPublishedDate partitions are reused. Complete XML status and ItemCount are validated before diffing. Failed or partial downloads never imply removal. If an established authority shows anomalous mass new/removal churn, its old partition remains committed, ordinary mass signals are suppressed, and run metadata sets humanReviewRequired while normal authorities continue.

Detected signals are persisted before CURRENT commit. A durable cursor advances only after successful Dataset writes. maxItems can split a large batch across several runs without losing changes; pending signals drain before new source processing. Deterministic signalId supports downstream deduplication around rare low-level partial failures.

Try it with sample data

{"mode":"sample"}

Sample mode makes zero external requests, uses no production KVS, is deterministic, and runs the production diff engine. It demonstrates FHRS 5→2, FHRS 2→5, pending-rating, later-inspection, and FHIS degradation.

Example live input

{"mode":"live","localAuthorities":["277"],"baselineOnly":true,"maxItems":100}

Schedule daily after the authority's normal publication time. A later run with unchanged authority markers skips downloads and emits zero rows.

Example output

{"signalId":"…","signalType":"RATING_DROPPED","severity":"HIGH","signalSummary":"Rating dropped from 5 to 2","detectedAt":"2026-01-02T00:00:00.000Z","sourceObservedAt":"2026-01-02T00:00:00.000Z","businessId":"1","businessName":"One","businessType":null,"address":null,"postcode":null,"localAuthority":null,"previousRating":"5","currentRating":"2","previousInspectionDate":"2025-01-01","currentInspectionDate":"2025-01-01","ratingValue":"2","schemeType":"FHRS","sourceUrl":"https://ratings.food.gov.uk/","previousValue":"5","currentValue":"2"}

Limitations and compute

FHRSID is the primary identity, but FSA notes IDs can change during database or authority migrations and can be retained if a local business ID is reused; the anomaly guard limits damage but cannot infer real-world continuity. Private-address fields may be absent. Whole-UK scope downloads many authority files and uses substantial network, memory, and KVS operations; a specific authority scope is recommended for focused monitoring. Data is source-publication current, not real-time.