Get started with geo-score · geo-score docs

geo-score scores a website from 0 to 100 on whether AI answer engines can reach, parse, trust and cite it, against the open AIV rubric v1.1. This page gets a first score on your screen, explains what the report says, and points to the rest of the docs. You need Python 3.8 or later and nothing else: no API key and no account.

What do I need to run geo-score?

The score (level 1) is one Python file that uses the standard library only. You can pipe it straight from the release tag, run the PyPI package with uv without installing it, or install the geo-score command with pipx or pip. Whichever you pick, the code is the same release, 1.8.3.

Python 3.8+, on macOS, Linux or Windows.
Network access to the site you score, to the URLs its markup points to, and to Wikidata and Wikipedia search.
No key. Keys are only needed for levels 2 and 3, which ask AI engines questions through their APIs.

How do I score a site?

Pick one line. Each prints the same report for the same pages.

uvx geo-score@1.8.3 example.com                    # run the PyPI package without installing it
pipx install geo-score==1.8.3                      # or install the geo-score command
pip install geo-score==1.8.3                       # pip works too, in a virtual environment
curl -sL https://raw.githubusercontent.com/jianruntech/geo-score/v1.8.3/cli/geo_score.py | python3 - example.com --brief

Without access to PyPI, install the wheel attached to the GitHub release; releases carry a SHA256SUMS file, and the wheel on PyPI matches it byte for byte. You can also try a site online on this website, which reads fewer pages and gives you the command to reproduce the result locally.

What does the report tell me?

The first screen carries three things: the score with its band, how far the next band is, and the biggest gaps. Below it, every check is listed with its tier.

Score and band. 0–100, normalised over the checks the run could observe, and one of five bands from Not started to Leading.
Pillars and checks. Five pillars, 21 tiered checks. Each check reads full, partial, zero, or not measured; a check that was not measured leaves the denominator and never counts as zero.
Biggest gaps first. Gates at zero lead, then the checks whose next tier adds the most points. Each gap says what the next tier needs.
The footer. Points scored out of points observable, which checks left the denominator and why, the rubric version, and how long the run took.

Add --explain to see the evidence behind every check: the status code, the count, the sentence that did or did not qualify. Since 1.7.0 the report also prints three observations outside the score (robots.txt rules page by page, links in the server HTML, hreflang annotations); they never move the score.

What are the three levels?

The score answers whether engines can cite a site. Two further levels measure whether they do, with your own API keys, and report it beside the score without ever adding it in.

Level	What it answers	Needs	Command
1 · Score	Can AI engines reach, parse, trust and cite the site?	Nothing	`geo-score example.com`
2 · Ask	For one question, do the engines cite it right now?	An API key for OpenAI, Perplexity, Gemini, Anthropic or OpenRouter	`geo-score example.com --ask "…"`
3 · Watch	How often is it cited for a fixed question set, week over week?	Your keys and a question list	`geo-score watch run`

The online scorer on this website runs level 1 only. It never asks an AI engine anything and uses no model key.

Where should I go next?

CLI reference: every flag, exit codes, comparing two runs.
GitHub Action: score on every push and fail the build on a regression.
MCP server: give an agent the same scorer.
How the score is calculated: every check, gate and band.
FAQ: why a score moves, why a check shows a dash, why a score is capped at 40.