Branch Coverage Drift Audit by Region and Category

Compare two dated snapshots of an authorized branch directory and see, per region and business category, where coverage fell, which branches disappeared, and whether the category mix drifted between snapshots.

The Actor works only on data you supply. It does not scrape Google Maps or any other site, makes no network requests to third-party sites, and uses no proxies.

What it reports

Dataset rows have a recordType:

• run_summary: totals, counts of flagged cells and regions, warnings and limitations.
• region_summary: per-region counts and a category-mix shift index (total variation distance, 0 to 1).
• region_category_cell: per region/category counts, missing branches, new branches, branches reassigned to or from other cells, share shift in percentage points, and a status.
• missing_branch: branches present in the baseline but absent from the current snapshot (capped by maxMissingBranchRows).

Cell statuses: coverage_gap, share_drift, low_sample, new_cell, stable. Region statuses: sampling_drift, low_sample, new_region, stable.

A branch that appears in both snapshots under a different region or category is counted as reassigned, not missing, so relabeling does not look like a coverage loss.

Sample input

{
  "authorizationConfirmed": true,
  "baselineDate": "2026-01-31",
  "currentDate": "2026-04-30",
  "baselineRecords": [
    {"branchId": "b1", "name": "Harbor Cafe", "address": "1 Pier Rd", "region": "North", "category": "Cafe"},
    {"branchId": "b2", "name": "Pine Cafe", "address": "2 Pine St", "region": "North", "category": "Cafe"},
    {"branchId": "b3", "name": "Oak Cafe", "address": "3 Oak St", "region": "North", "category": "Cafe"},
    {"branchId": "b4", "name": "Elm Cafe", "address": "4 Elm St", "region": "North", "category": "Cafe"}
  ],
  "currentRecords": [
    {"branchId": "b1", "name": "Harbor Cafe", "address": "1 Pier Rd", "region": "North", "category": "Cafe"},
    {"branchId": "b2", "name": "Pine Cafe", "address": "2 Pine St", "region": "North", "category": "Cafe"}
  ],
  "minBaselineSample": 3,
  "gapPercentThreshold": 30,
  "minMissingBranches": 2
}

Here the North/Cafe cell loses 2 of 4 branches (50%) and is flagged coverage_gap.

Instead of inline records you can pass baselineDatasetId and currentDatasetId for existing Apify datasets you own. Field names are configurable (regionField, categoryField, idField, nameField, addressField).

Input notes

• authorizationConfirmed must be true. currentDate must be later than baselineDate.
• Defaults in the input form (minBaselineSample 3, minMissingBranches 2, gapPercentThreshold 30) suit the tiny sample. For real data, start with a minimum sample of about 10 and a minimum of 3 missing branches, then tune.
• At most 50,000 records per snapshot are read (default 20,000) to keep memory low.

Limitations

• It measures differences between your two snapshots, not completeness of any public map or real-world place list.
• "Missing" means absent from the current snapshot; the branch may be closed, renamed or just not collected.
• Without a stable ID, matching uses normalized name plus address, so renames or address edits show as one missing and one new branch.
• Small cells are unreliable. Cells under the minimum baseline sample are marked low_sample and never flagged as gaps; shifts are only computed for regions that meet the minimum in both snapshots.
• Thresholds are practical heuristics, not statistical significance tests. Results are not legal, financial or operational guarantees.

Billing and errors

The code defines one pricing event, audit-completed, charged once after results are stored. Invalid input or any error ends the run without a charge. No payable plan is configured in this repository.

Local tests

Tests run offline with the standard library: python -m unittest discover -s tests -t .