Python walkthrough

revised_api_walkthrough.ipynb is the whole working flow in one notebook: authenticate, page the directory with a cursor, turn banded metrics into numbers you can sort on, rank them transparently, reveal a name, and export a shortlist you are allowed to publish.

It runs with or without an API key. Without one it falls back to a bundled snapshot of 30 real open-tier listings taken on 22 September 2026, and every later cell still executes — so you can read the output before you sign up for anything.

What it covers

Four things worth stealing

The paging loop. It stops on has_more rather than on an empty page, keeps a hard max_pages cap so a bad filter cannot run away with your rate-limit window, sleeps between requests, and keeps the synced_at watermark from the first page — which is the value you would pass as since on the next run.

band_midpoint. Four band shapes, one function, None preserved as None. The midpoint is for sorting; the band string is what you show a reader.

Missing components are dropped, not zeroed. The ranking re-normalises the remaining weights and reports a components_used column beside every score. A row scored on two of four components is a weaker claim than one scored on all four, even when its number is higher.

The export assertion.

assert (df["tier"] == "open").all(), \
    "refusing to export: non-open rows are disclosed under the API terms, not for republication"

It sits immediately before to_csv, not at the top of the cell, so no later edit to the filters can quietly bypass it. See Republishing rules.

What it does not do

It does not decide anything for you. A high rank score is a reason to look at a domain, not a reason to register one — the notebook’s closing section is a checklist for what to do afterwards: read the archive, confirm the links still exist on the live pages, confirm availability at a registrar, and have a plan for the content.

It also does not cover holds or the since change feed. Those are in Reveals and holds and Incremental sync.

Handling your key

The notebook reads the key with getpass, so it never lands in the notebook file and never ends up in saved output. Do not paste a key into a cell you intend to share.

_entered = getpass.getpass("Revised API key (rvd_...), or Enter to skip: ").strip()
API_KEY = _entered or None
LIVE = API_KEY is not None

Press Enter at that prompt and the notebook runs against the bundled snapshot instead.

About the snapshot

The bundled rows are genuine listings, every one on the open tier — the shelf whose names Revised publishes on its own site anyway. They span .com, .com.au, .net.au, .ai and .dev, and 28 of the 30 carry an Agent Citability score, so the ranking has something to work with offline.

They will go stale. A name somebody registers leaves the directory, which is exactly why the live path exists. Supply a key when you want current data.