Skip to content

PokeAPI client

HTTP client for PokeAPI. All responses are cached locally so the network is never hit during simulation once the cache is warm.

Retries up to 3 times on HTTP 429/5xx and network errors using a linear ramp with random jitter (250 ms, 500 ms, 750 ms + up to 100 ms jitter per attempt).

pokeapi

PokeAPI client -- fetches and caches Pokemon data.

Fetches once per Pokemon per generation and writes to cache/pokeapi/. Never hits the network during simulation if cache is warm.

fetch_pokemon_list 

fetch_pokemon_list(
    limit: int = 2000, force: bool = False
) -> list[dict]

Return the raw PokeAPI species list (name + url pairs).

Source code in pokerena/data/pokeapi.py 
82
83
84
85
def fetch_pokemon_list(limit: int = 2000, force: bool = False) -> list[dict]:
    """Return the raw PokeAPI species list (name + url pairs)."""
    data = _fetch_cached("pokeapi", "pokemon_list", f"{_BASE}/pokemon?limit={limit}", force=force)
    return data["results"]

fetch_pokemon 

fetch_pokemon(name: str, force: bool = False) -> dict

Return raw PokeAPI /pokemon/{name} payload, cached.

Source code in pokerena/data/pokeapi.py 
88
89
90
def fetch_pokemon(name: str, force: bool = False) -> dict:
    """Return raw PokeAPI /pokemon/{name} payload, cached."""
    return _fetch_cached("pokeapi", f"pokemon_{name}", f"{_BASE}/pokemon/{name}", force=force)

fetch_species 

fetch_species(name: str, force: bool = False) -> dict

Return raw PokeAPI /pokemon-species/{name} payload, cached.

Source code in pokerena/data/pokeapi.py 
93
94
95
96
97
def fetch_species(name: str, force: bool = False) -> dict:
    """Return raw PokeAPI /pokemon-species/{name} payload, cached."""
    return _fetch_cached(
        "pokeapi", f"species_{name}", f"{_BASE}/pokemon-species/{name}", force=force
    )

fetch_move 

fetch_move(name: str, force: bool = False) -> dict

Return raw PokeAPI /move/{name} payload, cached.

Source code in pokerena/data/pokeapi.py 
100
101
102
def fetch_move(name: str, force: bool = False) -> dict:
    """Return raw PokeAPI /move/{name} payload, cached."""
    return _fetch_cached("pokeapi", f"move_{name}", f"{_BASE}/move/{name}", force=force)

fetch_evolution_chain 

fetch_evolution_chain(
    url: str, force: bool = False
) -> dict

Fetch an evolution chain by its full URL.

Source code in pokerena/data/pokeapi.py 
105
106
107
108
109
def fetch_evolution_chain(url: str, force: bool = False) -> dict:
    """Fetch an evolution chain by its full URL."""
    # Derive a stable cache key from the URL id
    chain_id = url.rstrip("/").split("/")[-1]
    return _fetch_cached("pokeapi", f"evochain_{chain_id}", url, force=force)

get_generation_number 

get_generation_number(pokemon_data: dict) -> int

Extract the generation number (1-9) from a PokeAPI pokemon payload.

Source code in pokerena/data/pokeapi.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def get_generation_number(pokemon_data: dict) -> int:
    """Extract the generation number (1-9) from a PokeAPI pokemon payload."""
    # PokeAPI gives generation via species; caller must pass species data or
    # we derive it from the id range as a fallback.
    pid = pokemon_data.get("id", 0)
    # Approximate by national dex id
    if pid <= 151:
        return 1
    if pid <= 251:
        return 2
    if pid <= 386:
        return 3
    if pid <= 493:
        return 4
    if pid <= 649:
        return 5
    if pid <= 721:
        return 6
    if pid <= 809:
        return 7
    if pid <= 905:
        return 8
    return 9

parse_base_stats 

parse_base_stats(pokemon_data: dict) -> dict[str, int]

Return {stat_name: base_value} from raw PokeAPI pokemon payload.

Source code in pokerena/data/pokeapi.py 
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def parse_base_stats(pokemon_data: dict) -> dict[str, int]:
    """Return {stat_name: base_value} from raw PokeAPI pokemon payload."""
    stat_map = {
        "hp": "hp",
        "attack": "attack",
        "defense": "defense",
        "special-attack": "sp_atk",
        "special-defense": "sp_def",
        "speed": "speed",
    }
    result: dict[str, int] = {}
    for entry in pokemon_data["stats"]:
        key = entry["stat"]["name"]
        if key in stat_map:
            result[stat_map[key]] = entry["base_stat"]
    return result

parse_types 

parse_types(pokemon_data: dict) -> list[str]

Return list of type name strings (lower-case).

Source code in pokerena/data/pokeapi.py 
155
156
157
def parse_types(pokemon_data: dict) -> list[str]:
    """Return list of type name strings (lower-case)."""
    return [slot["type"]["name"] for slot in pokemon_data["types"]]

get_candidate_move_names 

get_candidate_move_names(pokemon_data: dict) -> list[str]

Return all move names this Pokemon can learn (any method).

Source code in pokerena/data/pokeapi.py 
160
161
162
def get_candidate_move_names(pokemon_data: dict) -> list[str]:
    """Return all move names this Pokemon can learn (any method)."""
    return [m["move"]["name"] for m in pokemon_data["moves"]]

get_evo_lines 

get_evo_lines(
    evolution_chain_data: dict,
) -> list[list[str]]

Return all evolutionary paths in a chain. Each path is a list of species names ordered from base to final stage.

Source code in pokerena/data/pokeapi.py 
182
183
184
185
186
187
def get_evo_lines(evolution_chain_data: dict) -> list[list[str]]:
    """
    Return all evolutionary paths in a chain.
    Each path is a list of species names ordered from base to final stage.
    """
    return _walk_evo_chain(evolution_chain_data["chain"])