Maps Branch Exception Escalation Audit

Reconcile a places export you already hold with your internal branch maintenance roster. The Actor lists the gaps as owner-actionable exceptions:

• missing_branch_record: a roster branch has no record in the places data.
• duplicate_identifier: the same place identifier repeats in the places data, or a branch/place identifier repeats in the roster.
• stale_review_date: the newest review for a matched branch is older than your threshold.
• missing_review_date: a matched branch has no usable review date.
• ambiguous_branch_match: a name-based match points to several different places.
• unrostered_place (optional): a place has no roster branch.

Each exception carries a severity, an escalation tier (owner_review or escalate_now), the owner and escalation labels from your roster, and a plain-language recommended action.

What it does not do

• It does not scrape or visit Google Maps or any other website. It runs offline on the rows you paste into the input.
• It does not contact, notify, or publish anything. Owner and escalation values are only labels in the output.
• It does not verify that a branch is open or that review data is correct.

Use it only with data you are authorized to process.

Input

Field	Description
places	Array of place rows. Recognised fields: placeId, title, postalCode, city, lastReviewDate.
roster	Array of roster rows. Recognised fields: branchId, placeId, branchName, postalCode, city, owner, escalateTo.
staleDays	Review age limit in days (default 180).
escalationGraceDays	Days beyond the limit before a stale branch becomes escalate_now (default 90).
referenceDate	YYYY-MM-DD used to compute age. Empty means today. Set it for reproducible reports.
defaultOwner	Label for exceptions without a roster owner.
includeUnrosteredPlaces	Report places missing from the roster (default true).
placeFieldMap, rosterFieldMap	Rename columns, e.g. {"id": "google_id"}.

Sample input

{
  "places": [
    {"placeId": "SAMPLE-PLACE-001", "title": "Example Fixtures Harbor", "postalCode": "10001", "city": "Harborview", "lastReviewDate": "2026-10-20"},
    {"placeId": "SAMPLE-PLACE-002", "title": "Example Fixtures Riverside", "postalCode": "10002", "city": "Harborview", "lastReviewDate": "2025-12-15"},
    {"placeId": "SAMPLE-PLACE-003", "title": "Example Fixtures Uptown", "postalCode": "10003", "city": "Harborview", "lastReviewDate": "2026-03-01"},
    {"placeId": "SAMPLE-PLACE-003", "title": "Example Fixtures Uptown", "postalCode": "10003", "city": "Harborview", "lastReviewDate": "2026-02-01"}
  ],
  "roster": [
    {"branchId": "BR-001", "placeId": "SAMPLE-PLACE-001", "owner": "Facilities North", "escalateTo": "Regional Operations"},
    {"branchId": "BR-002", "placeId": "SAMPLE-PLACE-002", "owner": "Facilities South", "escalateTo": "Regional Operations"},
    {"branchId": "BR-003", "placeId": "SAMPLE-PLACE-003", "owner": "Facilities North", "escalateTo": "Regional Operations"},
    {"branchId": "BR-004", "placeId": "SAMPLE-PLACE-004", "owner": "Facilities West", "escalateTo": "Regional Operations"}
  ],
  "staleDays": 180,
  "escalationGraceDays": 90,
  "referenceDate": "2026-11-01"
}

Output

• Dataset: one item per exception (exceptionId, type, severity, escalationTier, owner, escalateTo, branchId, placeId, branchName, summary, recommendedAction, details). Items are sorted by severity, then type. IDs are stable for the same input.
• Key-value store SUMMARY: counts by type, severity, tier and owner, match rate, thresholds, notes and limitations.

If everything reconciles, the dataset is empty and SUMMARY says so.

Matching rules

1. If a roster row has placeId, it matches places with that exact identifier. No name fallback is used when an identifier is given.
2. Otherwise it matches on normalised branch name plus postal code, then plus city. Several different candidates produce ambiguous_branch_match.

Limitations and sample-size caveats

• Results are only as good as the supplied rows. Missing identifiers or inconsistent names reduce match quality.
• Name-based matching is heuristic; check those matches before acting.
• A review date shows listing recency, not branch maintenance quality.
• With fewer than 30 roster rows, percentages in SUMMARY are indicative only; the Actor adds a note when this applies.
• Limits: 50,000 place rows and 20,000 roster rows per run, and the Apify input size cap applies to inline input.
• A broad market of Maps data users does not prove demand for this specific audit.

Pricing

The code defines one pricing event, audit-completed, charged once after a successful run. Failed runs and rejected input are never charged. No payable plan is configured in this project.

Local tests

The tests are offline and use only the standard library:

python -m unittest discover -s tests -t .