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 latest two Overture releases (or two pinned release ids)."
• "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: Overture release to observe. latest (default) follows the newest hosted release, previous the second-newest; a pinned id (e.g. 2026-10-21.0) is validated against what Overture hosts.
• releasePrevious: optional older release for comparison (previous or a pinned id); 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: whatever Overture currently hosts (about two monthly releases; on 2026-10-22: 2026-09-23.0, 2026-09-23.1, 2026-10-21.0); latest/previous follow retention automatically. The Places category struct was renamed from categories to taxonomy in the 2026-09-23 release; both are supported.
• 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.
• 2026-10-22 — Fixed the Apify quality-test failure caused by retired release 2026-08-19.0: release latest/previous tokens resolve against the hosted release listing, pinned ids are validated with an actionable error, and the categories → taxonomy schema rename is supported. Footer validation now uses an adaptive 1 MB window and S3 range requests are retried, keeping a full run well inside 5 minutes.