Local Rankings (GeoGrid)

All steps (reference)

1. Step 1. Open Local Rankings and pick a location

   The addon lives under "Local Rankings" in the project sidebar. Each tracked location has its own grid config and scan history. Project-level Places defaults (and Listing Alignment NAP, when that flag is on) live on **Project Settings → Local SEO**.

   What to do: Sidebar → Local Rankings (geo-grid.index) → open a location (or Add location).

   Where: geo-grid.index

   

   Expected (pass)

   • Location cards/list render with the latest visibility grade
   • Add location CTA visible

   Negative cases (must fail safely)

   • Addon inactive → geo-grid.upgrade or 403 on direct URL

2. Step 2. Set a default layout on the location (optional)

   On the Add/Edit location form, "Default layout" chooses Square grid or Radial rings for new scans. Radial reveals a "Default density" picker (Standard / Dense / Max). This only pre-selects the launcher — you can still change it per scan.

   What to do: geo-grid.locations.edit → set Default layout = Radial rings → choose a Default density → Save.

   Where: geo-grid.locations.edit

   

   Expected (pass)

   • Radial choice persists on the location config
   • Launcher opens pre-set to that layout + density

   Negative cases (must fail safely)

   • A deactivated preset falls back to the first active one at launch (no hard error)

   Tips

   • Leave it on Square for most businesses; switch to Radial for dense urban centers where a square grid is too coarse.

3. Step 3. Run a scan — choose Square or Radial

   On the location, click "Run a scan". In the slide-over, the Layout control toggles Square grid ⇄ Radial rings. Radial swaps the grid-size buttons for a Density picker (Standard / Dense / Max, each showing its point count, e.g. "~39 pts"), and the spacing dropdown relabels to "Ring spacing" (distance between rings). The credit estimate (points × keywords) updates live.

   What to do: Run a scan → Layout: Radial rings → pick a Density → set Ring spacing → Start scan.

   Where: geo-grid.locations.show (Run a scan slide-over)

   

   Expected (pass)

   • Density presets show live point counts; estimate reflects points × keywords
   • Over the plan node cap → advisory shown and Start disabled
   • Scan starts and redirects to the live results map

   Negative cases (must fail safely)

   • Radial is never charged the free first-scan promo price
   • Insufficient credits → Start disabled with a top-up link

   Tips

   • Density sets how many rings and how tightly spaced the points are; ring spacing sets how far the grid reaches. More points = more credits.

4. Step 4. Read the results — pins, heatmap, Grid Details

   The results map plots each point with its local-pack position (Top 3 green / Top 10 amber / Top 20 red / not-found gray); a radial scan draws concentric rings automatically. Use the Pins ⇄ Heatmap toolbar toggle for the smooth gradient view. The "Grid Details" pill (top-left of the map) expands to show created date, business, keyword, center point, Rings / Ring spacing (or Grid size), radius, coverage, average ranking, and local 3-pack visibility.

   What to do: geo-grid.runs.show → toggle Pins/Heatmap → expand the Grid Details pill.

   Where: geo-grid.runs.show

   

   Expected (pass)

   • Rings render for a radial run; Heatmap toggle overlays the banded gradient
   • Grid Details shows radius + coverage and relabels Rings / Ring spacing for radial
   • Clicking a pin opens its per-point detail

   Negative cases (must fail safely)

   • Cross-org run in the URL → 404

   Tips

   • Pins fill in live as each point is checked. If the live connection drops mid-scan (e.g. during a deploy), the map catches up on its own within a few seconds — no need to refresh.

5. Step 5. Compare scans and export the PDF

   Compare shows two scans of the same location side by side with a per-point delta — but only when their geometry matches (same layout, size/rings, spacing); a mismatch shows a notice instead of a bogus delta. The PDF export includes the rank heatmap and the radial geometry.

   What to do: geo-grid.runs.compare (pick A/B) and Export PDF on the results page.

   Where: geo-grid.runs.compare

   

   Expected (pass)

   • Same-geometry pair shows the delta; different geometry shows the incompatible-geometry notice
   • PDF downloads with the heatmap + N-ring / N×N header

   Negative cases (must fail safely)

   • Export while a scan is still running → blocked with a message

6. Step 6. When the Google listing itself changes

   A scan finds the business by its Google place ID. When that stops resolving across the grid, one Places lookup tells apart the three things it can mean — the listing was removed, marked closed, or renamed — and the location page says which. The healthy "Place ID linked" badge is replaced by the problem, and the Google Business Profile card below is marked **Last known**, because its saved rating and reviews are the last capture rather than the live listing. A removed listing usually means Google deleted and recreated it, which mints a **new** place ID the old anchor can never match again. That is why the panel offers "Pick the right listing" rather than promising the warning will clear itself: nothing but re-anchoring will clear it. A closed or renamed listing still exists, so those link to the listing and do clear on their own once Google confirms it.

   What to do: Open a location whose listing has changed (geo-grid.locations.show).

   Where: geo-grid.locations.show

   

   Expected (pass)

   • The healthy badge is replaced, not sat beside, by the problem
   • Google Business Profile card shows "Last known" and drops its View on Google link
   • Missing listings offer Google Business Profile; closed/renamed link to the listing itself

   Negative cases (must fail safely)

   • Most of the grid failed → no alert (our bad night is not their listing gone)
   • A business that has never ranked → no alert ("never found" is not "no longer found")
   • A viewer without manage permission → told an editor must re-anchor, not shown the button

   Tips

   • The warning is raised and retired by the same evidence — Google. A scan finding the business again does not clear a "marked closed", because a closed business still ranks.

7. Step 7. Choose how loud a project's alerts are

   Alert delivery is set per project, on **Project Settings → Notifications**, next to the DNS and Reputation switches. Leave it inheriting and each recipient's own preference applies; set it to say the same thing for everyone on this client. It governs movement alerts — coverage drops, rank slips, and the listing problems above. Scan-finished and scan-failed notices are separate, and which channel anyone receives on is still their own setting.

   What to do: Project Settings → Notifications → Local Rankings movement alerts.

   Where: projects.settings

   

   Expected (pass)

   • Blank means inherit — it is stored as null, not as a value
   • Only visible when the addon is available for the project

   Negative cases (must fail safely)

   • One recipient with two projects on different settings → each project is honoured separately, in one digest