How to Set Up Codex for Local SEO Audits (Full SKILL.md Included)

mkdir -p ~/.codex/skills/codex-seo-local/scripts

---
name: codex-seo-local
description: Use when the user asks about local SEO - Google Business Profile, GBP, map pack, local pack rankings, NAP consistency, citations, reviews, service-area business, local schema, location pages, or multi-location websites. Run from one URL; nothing to install beyond python3.
---
# Local SEO Scan

Analyze one URL for local-search evidence. The scanner detects business type
(brick-and-mortar / service area / hybrid) and industry vertical, extracts
NAP and LocalBusiness schema, then scores five dimensions. When a page has
no city, address, NAP, map or review signals, print NO LOCAL SIGNALS instead
of a score: text keywords alone do not make a page local.

## Run

```bash
python3 ~/.codex/skills/codex-seo-local/scripts/local_scan.py <url> [--json]
```

`--json` prints the full result set for the next step (analysis, list, or
fix queue).

## Business type detection

| Signal on page | Type |
|---|---|
| Street address (visible or in schema) | brick-and-mortar |
| Street address + service-area language | hybrid |
| "we come to you", "service area", "home visits", "serving X Y" only | service-area business (SAB) |
| None of the above | not-detected |

SABs skip embedded-map checks and get `areaServed` recommendations instead
of physical-address requirements.

## Industry vertical detection

| Vertical | Detected by | Schema subtype to require |
|----------|-------------|---------------------------|
| Restaurant | menu, reservations, cuisine, dine-in/takeout | `Restaurant`, not plain `LocalBusiness` |
| Healthcare | appointment, insurance accepted, HIPAA, physician | `MedicalClinic`, `Dentist`, `Hospital` |
| Legal | attorney, practice areas, free consultation | `LegalService` (do not use deprecated `Attorney`) |
| Home services | free estimate, licensed and insured, 24/7 | subtype + `areaServed` + `Service` |
| Real estate | MLS, listings, open house, brokerage | `RealEstateAgent` + listings |
| Automotive | VIN, test drive, dealership, service department | `AutoDealer` (not `VehicleListing`) |

## The five dimensions

| Dimension | Weight | 3 strongest signals | Common loss |
|-----------|--------|---------------------|-------------|
| Locality on page | 25% | city in title + H1, NAP visible | generic title, no click-to-call |
| Local schema | 20% | correct subtype, address, geo (5+ decimals) | plain `LocalBusiness`, no geometry |
| Reviews | 15% | aggregateRating, >=4.0 stars, >=10 count | no rating in schema, stale reviews |
| Service pages | 20% | one page per service, /locations/ links | doorway pattern (swap-test fails) |
| AI readiness | 20% | Yelp/TripAdvisor/BBB/Reddit presence, local FAQ | no platform mentions |

**Score gate:** print NO LOCAL SIGNALS when the page has no address, no
schema, no map and no tel link, regardless of keyword hits. A blog post can
say "reviews" without being a local business page.

## Review thresholds (benchmarks)

- 10 reviews = magic threshold (one-day visibility step).
- 18-day rule: rankings can cliff after ~3 weeks without a new review.
- 31% of consumers use only 4.5+ rating businesses; 68% use only 4+.
- 74% care only about reviews from the last 3 months.
- 88% would use a business that responds to reviews.

## Citation tiers

Tier 1: Google Business Profile, Yelp, BBB, Facebook.
Tier 2: Bing Places (it powers ChatGPT, Copilot, Alexa), Apple Maps.
Tier 3: Data aggregators - Data Axle, Foursquare, Neustar/TransUnion.
For AI engines: ChatGPT does not read GBP directly; it sources from Bing
index, Yelp, TripAdvisor, BBB and Reddit. 3 of the top 5 AI-visibility
factors are citation-related.

## Multi-location quality gates

| Volume | Gate |
|--------|------|
| Up to 30 location pages | validate >60% unique content per page |
| 30+ pages | WARNING: enforce the 60% unique rule |
| 50+ pages | HARD STOP: require justification before continuing |

Swap test: if swapping the city name changes nothing, it is a doorway page.
Distinct content per location page (local photos, area testimonials, local
FAQs) is a requirement, not an enhancement.

## Output contract

Produce `LOCAL-SEO-ANALYSIS-{domain}.md` with: score card (5 dimensions),
business type, vertical, GBP checklist, review snapshot, NAP audit, citation
status, schema status, location-page quality, top 10 prioritized actions,
and a limitations disclaimer (what could NOT be assessed: real-time local
pack position, GBP Insights, full backlinks).

## Errors

| Scenario | Action |
|----------|--------|
| URL unreachable | report the error; do not guess site content |
| NO LOCAL SIGNALS | confirm the site is a local business, get the GBP listing URL, re-run |
| Address absent but schema present | the schema may carry the full address; extract it before flagging |
| Vertical unclear | present the top two detected verticals and ask before applying vertical rules |
| 50+ location pages | HARD STOP per the quality gate above |

#!/usr/bin/env python3
"""Local SEO scan from one URL. Detects business type (brick-and-mortar,
service area, hybrid) and industry vertical, extracts NAP and LocalBusiness
schema, then scores five dimensions. Reports NO LOCAL SIGNALS instead of a
score when no local evidence exists at all.
Standard library only. Usage:
  python3 local_scan.py <url> [--json]
"""
import json
import re
import sys
import urllib.error
import urllib.request

TIMEOUT = 12
UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
      "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36 "
      "codex-seo-local/1.0")

VERTICALS = {
    "restaurant": ["menu", "reservations", "cuisine", "dine-in", "takeout",
                   "table for", "hours of operation"],
    "healthcare": ["appointment", "insurance accepted", "hipaa", "patient",
                   "physician", "dentist", "clinic"],
    "legal": ["attorney", "lawyer", "practice areas", "bar admission",
              "free consultation", "case results"],
    "home_services": ["free estimate", "licensed and insured", "24/7",
                      "emergency service", "service area"],
    "real_estate": ["mls", "listings", "for sale", "open house",
                    "brokerage", "sq ft"],
    "automotive": ["vin", "test drive", "service department",
                   "certified pre-owned", "dealership", "inventory"],
}
ADDR_RE = re.compile(
    r"\b\d{2,5}\s+[A-Z][a-zA-Z.]*(?:\s+[A-Z][a-zA-Z.]*){0,3}?"
    r"\s+(?:St|Street|Ave|Avenue|Blvd|Boulevard|Rd|Road|Dr|Drive|Ln|Lane|"
    r"Way|Ct|Court|Pl|Place|Trail|Parkway)\b")
ZIP_RE = re.compile(r"\b\d{5}(?:-\d{4})?\b|\b[A-Z]{2}\s+\d{5}\b")
MAP_RE = re.compile(r"maps\.google(?:\.com|usercontent)")
SERVICE_RE = re.compile(
    r"(we come to you|on-site service|service area|home visits|"
    r"serving [A-Z][a-z]+ [A-Z][a-z]+)", re.I)
LOCAL_KINDS = {"LocalBusiness", "Restaurant", "Dentist", "LegalService",
               "AutoDealer", "RealEstateAgent", "MedicalBusiness",
               "MedicalClinic", "Hospital", "BarOrPub", "CafeOrCoffeeShop"}


def fetch(url):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        resp = urllib.request.urlopen(req, timeout=TIMEOUT)
        return resp.status, resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, ""
    except Exception as e:
        return "ERR:" + str(e)[:60], ""


def find_jsonld(html):
    out = []
    for m in re.finditer(
            r'<script[^>]*type=["\']?application/ld\+json["\']?[^>]*>(.*?)'
            r'</script>', html, re.S | re.I):
        raw = m.group(1).strip()
        if not raw:
            continue
        try:
            data = json.loads(raw)
        except Exception:
            continue
        out.extend(walk_nodes(data))
    return out


def walk_nodes(node):
    if isinstance(node, dict):
        yield node
        for v in node.values():
            yield from walk_nodes(v)
    elif isinstance(node, list):
        for v in node:
            yield from walk_nodes(v)


def types_of(node):
    t = node.get("@type")
    if isinstance(t, list):
        return set(str(x) for x in t)
    return {str(t)} if t else set()


def business_type(html, schemas):
    street = bool(ADDR_RE.search(html)) or any(
        s.get("address", {}).get("streetAddress") for s in schemas)
    map_embed = bool(MAP_RE.search(html))
    svc = bool(SERVICE_RE.search(html))
    if street and svc:
        return "hybrid"
    if street:
        return "brick-and-mortar"
    if svc:
        return "sab"
    return "not-detected"


def detect_vertical(html):
    low = html.lower()
    hits = {k: sum(v in low for v in ws) for k, ws in VERTICALS.items()}
    top = sorted(hits.items(), key=lambda kv: -kv[1])
    return [(k, v) for k, v in top if v >= 2][:2]


def main():
    if len(sys.argv) < 2:
        print("local_scan.py - local SEO scan from one URL")
        print("  python3 local_scan.py <url> [--json]")
        return
    url = sys.argv[1]
    status, html = fetch(url)
    if status != 200:
        print("fetch failed: %s" % status)
        return
    schemas = [n for n in find_jsonld(html) if types_of(n) & LOCAL_KINDS]
    btype = business_type(html, schemas)
    verticals = detect_vertical(html)

    city = phone = street = ""
    typ = agg = addr = geo = s0 = None
    if schemas:
        s0 = schemas[0]
        typ = sorted(types_of(s0) & LOCAL_KINDS)[0]
        addr = s0.get("address") or {}
        geo = s0.get("geo") or {}
        agg = s0.get("aggregateRating") or {}
        street = addr.get("streetAddress", "")
        city = addr.get("addressLocality", "")
        phone = s0.get("telephone", "")

    def tag_text(tag):
        m = re.search(r"<%s[^>]*>(.*?)</%s>" % (tag, tag), html, re.S | re.I)
        return m.group(1) if m else ""

    title_meta = re.search(r"<title>(.*?)</title>", html, re.S | re.I)
    title = title_meta.group(1) if title_meta else ""
    h1 = tag_text("h1")
    tel = bool(re.search(r'href=["\']?tel:', html, re.I))
    maps = bool(MAP_RE.search(html))
    nap_visible = bool(street or ZIP_RE.search(html))
    low = html.lower()

    s_locality = 0
    if city and city.lower() in title.lower():
        s_locality += 5
    if city and city.lower() in h1.lower():
        s_locality += 5
    if nap_visible:
        s_locality += 5
    if tel:
        s_locality += 5
    if maps:
        s_locality += 5

    s_schema = 0
    if typ:
        s_schema += 6
        if typ != "LocalBusiness":
            s_schema += 4
        if addr and street:
            s_schema += 4
        if geo and len(str(geo.get("latitude", "")).split(".")[-1]) >= 5:
            s_schema += 3
        if s0 and (s0.get("openingHours")
                   or s0.get("openingHoursSpecification")):
            s_schema += 3

    s_reviews = 0
    if agg:
        s_reviews += 8
    try:
        if agg and float(agg.get("ratingValue", 0)) >= 4.0:
            s_reviews += 3
    except ValueError:
        pass
    if re.search(r"\breviews?\b", low):
        s_reviews += 2
    try:
        if agg and int(agg.get("reviewCount", 0)) >= 10:
            s_reviews += 2
    except ValueError:
        pass

    s_service = 0
    if len(re.findall(r'<a\b[^>]*href=', html, re.I)) >= 20:
        s_service += 8
    kw_hits = [k for k in ("menu", "services", "locations", "gallery")
               if re.search(r"\b%s\b" % k, low)]
    s_service += min(9, 3 * len(kw_hits))
    if re.search(r"/locations/|store locator|find a shop", low):
        s_service += 3

    s_ai = 0
    ai_platforms = [x for x in ("yelp", "tripadvisor", "bbb.org", "reddit")
                    if x in low]
    if ai_platforms:
        s_ai += 10
    if re.search(r"best (of|restaurant|service)|award|the most loved", low):
        s_ai += 5
    if re.search(r"\bfaq", low):
        s_ai += 5

    total = s_locality + s_schema + s_reviews + s_service + s_ai
    # Local SEO evidence = NAP/schema/map/tel. Text keywords are supporting
    # context, never enough by themselves to claim a local business page.
    no_signals = (not schemas and not street and not maps and not tel)

    out = {"url": url, "status": status, "business_type": btype,
           "vertical": [v for v, _ in verticals] or ["not detected"],
           "city": city, "phone": phone, "schema_type": typ or "none",
           "dimensions": {"locality_on_page": s_locality, "local_schema": s_schema,
                          "reviews": s_reviews, "service_pages": s_service,
                          "ai_readiness": s_ai},
           "total": "NO LOCAL SIGNALS" if no_signals else total,
           "no_local_signals": no_signals}
    if "--json" in sys.argv:
        print(json.dumps(out, default=str, indent=2))
        return

    print("local scan %s" % url)
    print("  status %s  business type: %s  vertical: %s" % (
        status, btype, ", ".join(v for v, _ in verticals) or "not detected"))
    print("  schema  : %s (%d blocks)   city: %s   phone: %s" % (
        typ or "none", len(schemas), city or "(unknown)", phone or "(none)"))
    if no_signals:
        print("  result: NO LOCAL SIGNALS")
        print("  No city, address, NAP, map, review or platform signals were found.")
        print("  Confirm the site serves a local business and re-run with the GBP URL.")
        return
    MAXES = {"locality_on_page": 25, "local_schema": 20, "reviews": 15,
             "service_pages": 20, "ai_readiness": 20}
    for name, v in out["dimensions"].items():
        print("  %-18s %3d/%d" % (name, v, MAXES[name]))
    print("  TOTAL: %d/100" % total)


if __name__ == "__main__":
    main()

python3 ~/.codex/skills/codex-seo-local/scripts/local_scan.py https://your-site.com
python3 ~/.codex/skills/codex-seo-local/scripts/local_scan.py https://your-site.com --json

local scan https://www.pequodspizza.com
  status 200  business type: brick-and-mortar  vertical: restaurant
  schema  : Restaurant (2 blocks)   city: Chicago   phone: +1-773-327-1512
  locality_on_page    20/25
  local_schema        14/20
  reviews              2/15
  service_pages       17/20
  ai_readiness        20/20
  TOTAL: 73/100

local scan https://auspia.ai
  status 200  business type: sab  vertical: restaurant
  schema  : none (0 blocks)   city: (unknown)   phone: (none)
  result: NO LOCAL SIGNALS
  No city, address, NAP, map, review or platform signals were found.
  Confirm the site serves a local business and re-run with the GBP URL.