ifpa-api 0.4.4

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

IFPA API Python

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/

• Quick Start Guide
• API Reference
• Practical Examples
• Migration Guide (0.2.x → 0.4.x)

License

MIT License — see LICENSE file.

---

Not affiliated with or endorsed by IFPA.