Ghost Engine

Appearance

geogrid-scanner ​

Fresh

Source: BIBLE.md (Roadmap #1 Phase 6, geogrid-scanner 5 routes)

Map pack rankings at grid points (neighborhoods or zip codes). Heatmap visualization on dashboard. Tracks changes over time per grid point.

What it does ​

flowchart LR
  K[Keyword: junk removal dallas] --> G[Generate lat/lng grid]
  G --> P[For each point: search with geo]
  P --> R[Capture rank at that point]
  R --> H[Heatmap matrix]
  H --> C[Compare to previous scan]

Routes (5) ​

MethodRouteWhat
POST/geogrid/scanExecute grid scan
GET/geogrid/scansList scans
GET/geogrid/scans/:idSingle scan with heatmap data
GET/geogrid/compareCompare two scans for movement
POST/geogrid/scheduleSchedule recurring scan

Example payload ​

bash
curl -X POST http://localhost:4700/geogrid/scan \
  -H "Content-Type: application/json" \
  -H "x-api-key: ghost-engine-key" \
  -d '{
    "keyword": "junk removal",
    "domain": "journeyjunkremoval.com",
    "center": { "lat": 32.7767, "lng": -96.7970 },
    "radiusMiles": 15,
    "gridSize": 7
  }'

A 7x7 grid centered on Dallas covering a 15-mile radius produces 49 rank samples. Each sample is the domain's map pack position at that lat/lng.

Heatmap data ​

Returns a matrix:

json
{
  "scanId": "geo-abc123",
  "keyword": "junk removal",
  "domain": "journeyjunkremoval.com",
  "gridSize": 7,
  "radiusMiles": 15,
  "center": { "lat": 32.7767, "lng": -96.7970 },
  "matrix": [
    [3, 5, 7, 9, null, null, null],
    [2, 4, 6, 8, 11, null, null],
    [1, 3, 5, 7, 9, 13, null],
    ...
  ],
  "summary": {
    "ranked": 32,
    "unranked": 17,
    "avgRank": 6.4,
    "bestRank": 1,
    "topQuadrant": "NE"
  }
}

Comparison ​

bash
curl "http://localhost:4700/geogrid/compare?from=geo-abc123&to=geo-def456"

Returns per-point delta and "moved up/down/same" summary.

How it fits with other plugins ​

  • Uses core/geo-profiles for lat/lng calculations
  • Uses mobile-serp or serp-tracker for per-point SERP scraping
  • Persistence at data/ghost-engine/geogrid-scans/