🐍 airanks — the AIR Python SDK

What is AIR? AIR (Artificial Intelligence Ranking) by airanks makes AI optimization visible — a 0–10 score for how often, and how well, an AI assistant like ChatGPT cites a given domain when answering real questions. Look up any site's AIR score at airanks.net, or install the browser toolbar to see it while you browse.

airanks is the Python door into that data: one client class, three methods, one dependency. No CLI, no scaffolding — pip install, import, go. 🚀

📚 Table of contents

• What is AIR?
• Install
• Quickstart
• API reference
• Shared authentication
• How auth resolution works
• Error handling
• Testing
• The AIR ecosystem
• License

📦 Install

pip install airanks

Requires Python 3.9+. One runtime dependency: requests. Ships a py.typed marker, so your type checker sees real annotations, not Any soup.

git clone https://git.shoemoney.ai/shoemoney/airanks-oss.git
cd airanks-oss/python-sdk
pip install -e .

⚡ Quickstart

from airanks import AirClient

client = AirClient()

domain = client.domain("stripe.com")
print(domain["data"]["air_score"])  # 0-10

results = client.search("payment processing")
who = client.user()  # raises ApiError(401) if unauthenticated

A fuller example with error handling lives in examples/lookup.py — run it with python examples/lookup.py stripe.com.

🔌 API reference

AirClient is the whole surface area. Three methods, all GET, all JSON in and out:

Constructor:

AirClient(api_key: str | None = None, api_base: str | None = None)

🔐 Shared authentication

One login works across every AIR client. Run air login once from the air CLI or the browser toolbar, and this SDK picks up the same token — no separate config, no re-auth.

Resolution order (first hit wins), identical across every AIR client — the air CLI, the browser toolbar, and every other language SDK in the ecosystem:

Skip all of that and use a key unconditionally:

client = AirClient(api_key="your-token-here")

🧭 How auth resolution works

flowchart TD
    Start(["AirClient() constructed"]) --> Explicit{"api_key passed\nto constructor?"}
    Explicit -- yes --> UseExplicit["source = explicit\nalways attaches"]
    Explicit -- no --> Env{"AIR_API_KEY\nenv var set?"}
    Env -- yes --> UseEnv["source = env\nalways attaches"]
    Env -- no --> File{"~/.config/air/auth.json\nreadable + has token?"}
    File -- yes --> UseFile["source = file\nattaches ONLY if\nrequest host == saved host"]
    File -- no --> Anon["source = anonymous\nno Authorization header"]

    UseExplicit --> Request["client._get(url)"]
    UseEnv --> Request
    UseFile --> HostCheck{"urlparse(url).hostname\n== saved host?"}
    Anon --> Request
    HostCheck -- yes --> Attach["Authorization: Bearer <token>"]
    HostCheck -- no --> NoAttach["request sent unauthenticated"]
    Attach --> Request
    NoAttach --> Request

🚨 Error handling

Non-2xx responses (and transport failures — timeouts, DNS errors) raise airanks.ApiError:

from airanks import AirClient, ApiError

client = AirClient()
try:
    domain = client.domain("example.com")
except ApiError as e:
    if e.status_code == 429:
        time.sleep(e.retry_after or 30)

The error message is pulled from the response body ({"error": {"message": ...}} or the 422 shape {"message": ...}), falling back to a generic "API returned {status_code}".

🧪 Testing

tests/test_auth.py covers token-resolution order and the host-scoped attach rule — no network calls, fully offline:

pip install -e ".[dev]"   # or: pip install -e . pytest
pytest

🌐 The AIR ecosystem

airanks (this package) is one door into AIR. Same API, same shared auth, different language:

Why AIR: search used to be the whole game — now the traffic that matters is an AI assistant deciding whether to cite you at all, and that's a different AI optimization problem than classic SEO. AIR exists to make that measurable, with a 0–10 score backed by real observed citations, not a self-reported checklist. This client returns the same numbers airanks.net and the browser toolbar show — available from Python.

📄 License

MIT — see LICENSE.