Geo‑Score – Auditing a Site’s AI‑Readiness for Citation

What the project does

geo‑score is a lightweight, Python‑only 3.8+ command‑line tool that evaluates how easily large‑language‑model answer engines (‑‑ ChatGPT / Perplexity / Gemini / Claude / OpenRouter) can discover, parse and cite content from a given website. It implements an open, versioned rubric (21 checks, 100 points + bonus) that measures:

• Reachability – can crawlers fetch the page (robots.txt, server‑rendered HTML, AI‑user‑agents)?
• Understandability – does the site expose structured data (JSON‑LD, llms.txt, schema.org, sitemaps, breadcrumbs)?
• Content citability – are there self‑contained answer passages, relevant headings, fresh data, sourced statistics, verifiable authors?
• Brand credibility – knowledge‑graph entity, third‑party listings, sameAs links, video/multimodal assets.
• Answer fit – is the content shaped for extraction by LLMs?

The tool returns a 0‑100 score (Level 1) and optionally:

• Ask a single question to the selected AI providers (Level 2) to see whether the site is actually cited in the generated answer.
• Watch a weekly set of questions, storing runs and producing diff reports (Level 3) for longitudinal monitoring.

All checks are deterministic, run against the public URL, and the rubric version is baked into the report.

How it works (high‑level)

1. Fetch the target URL (or a sample of pages) using only the Python standard library.
2. Inspect robots.txt, HTTP headers, HTML source, and any JSON‑LD blocks.
3. Apply the rubric: each check has tiered thresholds (e.g., “3 of 5 sampled pages have a sitemap”).
4. Score each pillar, sum to a total, and map the total to a band (Not started → Leading).
5. (Level 2/3) Call external LLM APIs with the user‑provided keys, ask the supplied question, and parse the answer for citations.
6. Report – human‑readable table, JSON schema, or embeddable SVG badge.

The CLI is a single script (cli/geo_score.py) with no third‑party dependencies; the optional watch functionality lives in cli/geo_watch.py. An MCP‑compatible server (geo-score-mcp) wraps the same logic for IDE‑integrated agents (Claude, Cursor, VS Code, LM Studio, etc.).

Who might use it

Audience	Why it matters
Web‑site owners / product teams	Know whether their content will be quoted by AI answer engines and which technical fixes (robots.txt, schema, fresh headings) will raise the score.
SEO / content strategists	Complements traditional SEO by focusing on citation rather than ranking; helps prioritize “AI‑ready” improvements.
LLM‑powered search platforms	Provides a reproducible audit of a source’s suitability for retrieval and citation, useful for source‑ranking algorithms.
Developers of AI agents	The MCP server lets agents request scores, ask questions, or run weekly watches programmatically.

Strengths & limitations

Strengths

• Zero‑install core – a single Python file works on any system with Python 3.8+.
• Transparent rubric – fully versioned, publicly viewable, with evidence tables explaining the empirical basis of each check.
• Open‑source & reproducible – the same command that produced the public leaderboard can be run locally; results are stable (≈96 % within ±5 points across runs).
• Extensible via MCP – agents can invoke the three levels programmatically, and the tool respects read‑only mode for security‑sensitive environments.

Limitations

• Heuristic language handling – non‑English pages (especially Chinese) are scored more conservatively; the tool may miss some citations that a human auditor would see.
• Citation check is indirect – Level 2 only asks a single question per engine; it does not guarantee coverage for all possible queries.
• Relies on public APIs – Level 2/3 need valid API keys and incur cost; the tool itself does not provide a free citation service.
• Focused on web‑content – Does not evaluate other media (PDFs, PDFs behind auth, private docs) beyond what the public crawler can fetch.

Quick start example

# Level 1 – free score (no keys needed)
curl -sL https://raw.githubusercontent.com/jianruntech/geo-score/v1.8.0/cli/geo_score.py \
  | python3 - stripe.com --brief
# → "72 / 100   Solid"

# Level 2 – ask a question (requires an OpenAI key, for example)
export OPENAI_API_KEY=sk-…
python3 cli/geo_score.py stripe.com \
  --ask "best payments API for marketplaces"

# Level 3 – start a weekly watch (needs a config file with a question list)
python3 cli/geo_watch.py run --dry_run   # shows planned API calls without spending

Where to find more

• Rubric – rubric/v1.1.md (full specification) and rubric/evidence-v1.1.md (empirical backing).
• Leaderboard – live scores for 324 sites: https://www.jianruntech.com/leaderboard.
• Installation – uvx geo-score@1.8.0, pipx install geo-score==1.8.0, or the one‑liner curl | python3.
• MCP integration – see guide/mcp.md and the auto‑generated tool table in the README.
• Contributing – PRs welcome; the repo includes benchmarks, reproducibility docs, and a test suite.

---

Geo‑Score is a genuine, open‑source utility for measuring a website’s readiness to be cited by generative AI answer engines, bridging the gap between classic SEO and the emerging field of Generative Engine Optimization (GEO).