Chain Location Network Monitor (Overture Places)

Chain location network events

Compare observed chain/brand locations between an older and newer Overture Places release (or against a saved baseline) within a selected area. Reports newly observed, no-longer-observed, changed and uncertain-match records — source observations only, not confirmed business events.

When should an AI agent use this?

• "Compare observed Starbucks, Albert Heijn and Jumbo locations in an Amsterdam area between the Overture releases 2026-07-22.0 and 2026-08-19.0."
• "Record a location baseline for the brand list ["Albert Heijn"] in bounding box [4.88, 52.36, 4.91, 52.38], without comparing releases."
• "Which chain records changed between these two pinned releases: which IDs are shared but have different categories, addresses, confidence or bbox?"
• "Identify records where brand is null but the name contains the brand text, flagged as uncertain matches."

Input

• brands: string array of tracked chain/brand names (also matched against the record's names.primary).
• bbox: WGS84 bounding box for the observed area; only intersecting rows are decoded.
• releaseCurrent: pinned Overture release (e.g. 2026-08-19.0).
• releasePrevious: optional second release for comparison; if omitted with trackChanges, compares against the saved snapshot for this config.
• matchMode: brandField (strict, requires the brand.names.primary field) or brandOrName (default, allows name matches but marks them as less certain).
• minConfidence: excludes low-confidence records.
• categoriesBlock: excludes records whose primary/basic category is in this list (e.g. casino, transportation).
• maxBytesPerRelease: per-release download budget cap; extraction stops and reports incomplete without emitting false disappearance events.

Output (dataset schema)

• recordType: summary / location / change
• Change records (changeType): newly_observed, no_longer_observed, changed, uncertain_match, first_observation
• Per-change fields: event id, current and previous names/coordinates/addresses/confidence/status, changed-fields list, release pair, source licenses
• Per-location fields: brand, name, category, bbox, confidence, operating status (nullable), source licenses
• summary: observed counts, event counts, extraction completeness (complete), bytes fetched, config hash (configHash), explicit warnings

Fixture evidence

The fixtures release-juli.json (56 records) and release-augustus.json (55 records) are included in tests/fixtures/ and used by the unit tests. They cover: substring false positives (Albert Heijn Spelen casino), category mismatches (transportation record with Starbucks brand), address/coordinate changes, shared IDs (53), additions (2) and removals (2), plus explicit source-license provenance per contributor (CDLA-Permissive-2.0, CC0-1.0, Apache-2.0).

This evidence supports the claim that the actor reports source-level observations reliably. It does NOT establish that any new/removed/changed record equals a real-world opening/closure/relocation; the MVP scope explicitly avoids that claim.

Pricing (suggested, not set)

• location-snapshot: cheap per observed location (low enrichment).
• network-change: priced higher for newly_observed / no_longer_observed / changed events, lower for snapshot / first_observation. No pricing is set in this local build; set via STOREINFO.md before any apify push.

Technical

• Pure matching (brands.ts), defensive mapping (places.ts), network diff (network.ts), config isolation (config.ts), bounded reading (overture.ts).
• Named key-value store per actor (vestigingennetwerk-monitor-snapshots) for cross-run history; deterministic event IDs and replay idempotence are required.
• maxBytesPerRelease: hard budget cap; extraction aborts cleanly on over-cap, timeout or unexpected range response.
• Source releases: 2026-07-22.0 and 2026-08-19.0; schema documented v1.18.0; retention is about two releases / 60 days (see docs/databronnen/overture-places-parquet.md).
• No personal profiles; only public company/chain location observations.
• Legal: source records carry per-source licenses (sources[].license). Preserve them in output; do not claim a single universal license.
• Build: npm run build + npm test pass locally; npm run typecheck and workspace test must also pass before any publish (PUBLISHING_INFO.txt and build checklists document this).

Related Actors

• nl-poi-finder-cbs-buurtverrijking — existing POI/CBS actor, complementary for broader POI context.
• The nl-studentenwoonruimte-monitor snapshot-change-detection pattern (pure comparison, budget-aware delivery, named KV snapshot, idempotent replay) is reused; this actor differs by comparing external fixed releases rather than scraping a live site.

Changelog

• 2026-09-17 — MVP scope written, source validated (two releases, 55/56 fixtures, bounded query ~33/28 MB per release, 21 usable chain-candidates after noise filters), actor scaffolded (vestigingennetwerk-monitor). Not published.