Maps & Local Rank Check (LRC)

The FCR-built maps subsystem: the rank-check grid, the local-insights map, and how the three map flows (LRC, Dashboard Discovery, Prospect) differ — plus which external service supplies each data point. All maps are served by the Worker as self-contained HTML (Leaflet) and shared via /r/:id. This is FCR's own LRC — separate from InSites/SayMore's LRC.

For the client-facing "how to read the report" explainer see lrc-methodology.md. Grid-sizing maths: LRC_Grid_Sizing_Brief.md. Verified 2026-05-20.

1. FCR LRC vs InSites LRC

There are two "LRC"s — don't conflate them:

• FCR LRC (this doc) — our own rank check, computed by querying SerpAPI at a grid of points. Canonical. Lives in the Worker (serp-grid, grid-map-build). Predictable credit cost, real per-point coordinates.
• InSites LRC — SayMore's third-party rank check (submitted via InSites). Used for the home anchor grid historically; being sunset in favour of SerpAPI as the canonical source.

2. How the LRC grid computes

dashboard-serp-grid is the engine:

1. Take a centre lat/lng, a size (e.g. 5 → 5×5 = 25 points), and a spacing_km. Generate a size × size grid of real coordinates.
2. For each point × each keyword, query SerpAPI engine=google_maps and read the top-20 local pack results.
3. Return the per-point results in an InSites-LRC-compatible shape, so the map builder treats SerpAPI and InSites grids uniformly.
4. The prospect's rank at each point = its position in that point's local pack (or "not in top 20"). Across the grid that's the heatmap of where they rank well vs poorly.

Key compute details:

• Zoom is auto-derived from spacing (not hardcoded). A wide zoom let city-centre giants (e.g. "Temple Bar Pub") rank #1 at every point and buried the actual prospect — tighter zoom = genuinely local results. (Fixed 2026-04-26.)
• Irish-leak guard: each SerpAPI response is validated for Irish signals (county names, eircode) and retried once with a tighter location string if it drifts to US results.
• Geometry (lib/grid-geometry.js): coverage_km per grid + satellite overlap analysis, so multi-grid layouts don't double-cover the same area (the check_satellite_overlap advisor tool uses this before burning SerpAPI).
• Catchment radius by place type (metro vs regional, Place vs SAB) is set in grid-map-build.js — see reference notes; 12/20/25/50 km tiers.

grid-map-build then assembles the shareable map from the grid + the other layers (below) and renders the /r/:id HTML with four sidebar tabs: Rankings · Demographics · Competitors · Web Results.

3. The three map flows

All three produce a Leaflet map; they differ in who drives it and how much is automated.

In short: LRC is the map primitive; Discovery is the guided in-dashboard builder around it; Prospect is the multi-grid meeting-prep flow.

4. Which service supplies which data point

The maps call several services — one per data point:

So a single LRC/Discovery map can fan out to SerpAPI (ranks + web), Pleper (GBP), Google Maps (places), CSO (demographics/PP), Meta (reach), and the Keyword KB (keywords) — each layer from its own source.

5. Map features

• Local insights map (Area Intelligence) — dashboard-area-map: the layers map of an area (purchasing power, population density, housing tenure, commercial properties, deprivation, Meta reach). Sourced from CSO + Meta. Standalone, or as the Demographics tab on an LRC map.
• "Quick — who ranks locally?" — the light competitor path (~3-4s, NOT a full grid): search_google_places (category + locality) → enrich_competitors. Returns competitors with reviews/hours/category breadth + threat level, without burning a SerpAPI grid. Used in the HubSpot card / Roam for a fast answer; escalate to run_serp_grid only when the AM asks for actual rank/SERP.
• Identify key competitors — dashboard-competitor-enrich / enrich_competitors: for a set of place_ids, adds services, photo count, response rate, hours, all GBP categories, and fcr_link (whether each is already on FCR's books) — surfacing a natural competitor to benchmark against and cross-sell from.

6. Where it's rendered & shared

• All maps are Worker-served HTML (Leaflet from CDN, data inlined) — no separate front-end build. The dashboard UI embeds them; clients open them via the public /r/:id share URL.
• The published map message + the four-tab explainer is what the advisor surfaces when it publish_grid_maps (see the advisor tooling).
• Client-facing methodology (how ranks are measured, how to read each layer): lrc-methodology.md — served at dashboard-lrc-methodology.

FCR Dashboard documentation · generated from docs/ · keep counts verified, not guessed.