IFPA API Python

AI Code Review

Unofficial Python client for the IFPA (International Flipper Pinball Association) API.

Access player rankings, tournament data, and statistics through a clean, type-safe Python interface with Pydantic validation.

Installation

pip install ifpa-api

Requires Python 3.11+.

Quick Start

from ifpa_api import IfpaClient

# Initialize (uses IFPA_API_KEY environment variable)
client = IfpaClient()

# Get player by ID
player = client.player.get(2643)
print(f"{player.first_name} {player.last_name}")

# Access stats
stats = player.player_stats["system"]["open"]
print(f"WPPR Rank: {stats['current_rank']}")

# Search with filters
results = client.player.search("John") \
    .country("US") \
    .state("CA") \
    .limit(10) \
    .get()

# Get rankings
rankings = client.rankings.wppr(count=100)
for entry in rankings.rankings[:10]:
    print(f"{entry.rank}. {entry.player_name}")

# Get tournament results
results = client.tournament(67890).results()
for result in results.results[:5]:
    print(f"{result.position}. {result.player_name}: {result.points} pts")

Features

Type-safe: Full type hints and Pydantic validation with IDE autocomplete
Fluent API: Chainable query builder for complex searches
46 Endpoints: Complete IFPA API v2.1 coverage across 7 resources
Automatic Pagination: Memory-efficient iteration with .iterate() and .get_all()
Enhanced Errors: Structured exceptions with request context for debugging
99% Test Coverage: Comprehensive unit and integration tests

Resources

Players — Search, profiles, rankings, tournament results, head-to-head
Tournaments — Search, details, results, formats
Rankings — WPPR, women, youth, country, age-based
Series — Circuit standings, player cards, region data
Stats — Overall metrics, largest tournaments, player activity
Directors — Search, tournament listings

Documentation

Full documentation: https://johnsosoka.github.io/ifpa-api-python/

AI Code Review

All pull requests are automatically reviewed by GPT-4o via ai-code-review. The AI checks for code quality, security issues, performance concerns, and maintainability.

Reviews run on every PR open and update. Results are posted as inline comments on the pull request.

License

MIT License — see LICENSE file.

Not affiliated with or endorsed by IFPA.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ifpa_api-0.4.12.tar.gz (53.6 kB view details)

Uploaded Aug 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ifpa_api-0.4.12-py3-none-any.whl (73.8 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

Details for the file ifpa_api-0.4.12.tar.gz.

File metadata

Download URL: ifpa_api-0.4.12.tar.gz
Upload date: Aug 10, 2026
Size: 53.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ifpa_api-0.4.12.tar.gz
Algorithm	Hash digest
SHA256	`92227659bef59e75c27eb4203273a350fe1749540eefb053a55d3b28a2c78d05`
MD5	`aae085d2cacefb471e46e287799dda35`
BLAKE2b-256	`fe40093d28153be7d8d61b107b075847a46b58a9f919090531996ac088e9334e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ifpa_api-0.4.12.tar.gz:

Publisher: publish.yml on johnsosoka/ifpa-api-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ifpa_api-0.4.12.tar.gz
- Subject digest: 92227659bef59e75c27eb4203273a350fe1749540eefb053a55d3b28a2c78d05
- Sigstore transparency entry: 2410662219
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: johnsosoka/ifpa-api-python@b4f4c007d37279879e6455c021fbc19637e2393c
- Branch / Tag: refs/tags/v0.4.12
- Owner: https://github.com/johnsosoka
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@b4f4c007d37279879e6455c021fbc19637e2393c
- Trigger Event: push