URL: /docs/examples/python-walkthrough

---
title: Python walkthrough
description: A runnable Jupyter notebook that pages the directory, flattens the banded metrics, ranks what comes back, reveals a name and exports a shortlist.
---

`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.

<CardGroup cols={2}>
  <Card title="Open in Colab" icon="play" href="COLAB_URL_PENDING">
    Nothing to install. `requests` and `pandas` are already there.
  </Card>
  <Card title="Download the notebook" icon="download" href="/docs/examples/revised_api_walkthrough.ipynb">
    Python 3.9+, `requests` and `pandas`. MIT licensed — copy the code.
  </Card>
</CardGroup>

## What it covers

| Section | What you get out of it |
| --- | --- |
| 1. `GET /api/v1/me` | Why this is always the first call: plan, remaining reveals, rate limit, change-feed access. |
| 2. `tier` | The three shelves, and the two independent reasons `domain` can be `null`. |
| 3. Categories | All 20 codes with their listing counts, because there is no categories endpoint on the REST API. |
| 4. Paging | A cursor loop with a page cap, a pause between requests, and the watermark taken from the first page. |
| 5. Bands | A parser for `"10-50"`, `"<100"`, `"250+"` and `"1K-5K"`, and why the API publishes ranges instead of numbers. |
| 6. Ranking | A four-component weighted score with the weights on the outside, where you can argue with them. |
| 7. Reveal | The only call that can spend, why it is free here, and why `availability_checked_at` is not a live check. |
| 8. Export | A CSV write with a `tier == "open"` assertion immediately in front of it. |

## 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.**

```python
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](/docs/guides/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](/docs/guides/revealing-and-holds) and [Incremental sync](/docs/guides/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.

```python
_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.