Step 02

Riot ID → PUUID (stable player ID)

Transform GameName#TAG into the long PUUID that unlocks match history.

Run

Run after each small change. Tiny loops win.

uv run python -m src.scout

You will touch

src/scout/ (your account fetch)
data/raw/

Time

45–75 minutes

Do this (suggested order)

Choose where your API key lives (recommended: env var like RIOT_API_KEY).
Parse Name#TAG into gameName + tagLine.
Call the account endpoint (platform host) with header X-Riot-Token.
Save the raw JSON to data/raw/account_<riotid>.json.
Extract puuid from the JSON and print it.

You’ll practice

Pass API keys via headers
Pick correct regional host (routing values matter!)
Handle error codes without panic

Explainers (for context, not homework)

API keys + env vars — Keep secrets out of your code
HTTP + JSON in 12 minutes — Status codes + what to print
Routing values (platform vs regional) — The “wrong host” bug

Build

Config

Choose env var (recommended) or local untracked file for API key

Request + save

Parse “Name#TAG” into gameName + tagLine
Call account endpoint
Save to data/raw/account_<riotid>.json
Extract and print puuid

Check yourself

Program prints the PUUID and writes account_*.json.

If it breaks

Wrong regional routing host
Forgetting the X-Riot-Token header
Typo in Riot ID (missing #)

Hints (spoilers)

Hint: which endpoint? (the one that literally says “by riot id”)

Use the account endpoint that says “get by riot id”. If you can print the full URL you’re hitting (host + path + encoded name/tag), you’re basically there.

Receipt #1: print the URL (safe)

print('URL:', url)

Bigger hint: where to put the API key (env var = easiest to not leak)

Put the key in an environment variable like RIOT_API_KEY, then read it with os.environ.get. That keeps secrets out of your code and out of screenshots.

The pattern

import os

api_key = os.environ.get('RIOT_API_KEY')
if not api_key:
  raise RuntimeError('Missing RIOT_API_KEY env var')

Bigger hint: auth header (the one name that matters)

Send your dev key in header X-Riot-Token. If you get 401/403, print status + the first 200 chars of response text.

Header name (copy/paste)

X-Riot-Token: <your-dev-key>

Unblock-me: keys expire (sudden 403 = not your fault)

Dev keys deactivate every ~24h. If everything is suddenly 403, it’s probably the key, not you. Regenerate the key and rerun.

Unblock-me: Riot IDs have spaces and # (URL-encode them)

If your name has spaces or weird characters, you can’t just glue strings into a URL. Use URL-encoding for the path parts.

Tiny helper

from urllib.parse import quote

game_name_enc = quote(game_name)
tag_line_enc = quote(tag_line)

Expected raw file

data/
  raw/
    account_<riotid>.json

Header name (the important part)

X-Riot-Token: <your-dev-key>

Print receipts when it fails

Don’t print secrets. Do print the URL, params, status, and a tiny slice of the body.

print('URL:', url)
print('STATUS:', r.status_code)
if r.status_code != 200:
  print('BODY:', r.text[:200])

Emotional support line

When dev keys expire, it feels like the universe is gaslighting you. It isn’t. Regenerate the key and keep rolling.