IFPA API Python Client

A comprehensive, type-safe Python client for the International Flipper Pinball Association API. Provides access to 46 endpoints across 7 resources with 99% test coverage.

IFPA API Python Client

A comprehensive Python client library for interacting with the International Flipper Pinball Association (IFPA) API. This library provides a clean, Pythonic interface for accessing player rankings, tournament data, and historical pinball statistics.

About IFPA

The International Flipper Pinball Association (IFPA) is the governing body for competitive pinball worldwide. In 2025 alone, IFPA sanctioned over 14,000 events with 318,000+ player attendances from 42,000+ unique players. The IFPA maintains the World Pinball Player Rankings (WPPR) and organizes the World Pinball Championship.

Features

Comprehensive API Coverage

• 46 API endpoints across 7 resource types
• Players: Search, profiles, results, head-to-head comparisons
• Directors: Search and tournament management data
• Tournaments: Events, results, formats
• Rankings: WPPR, women’s, youth, and age-based
• Series: Standings and player cards
• Stats: Top earners and largest tournaments

Type Safety & Quality

• 99% test coverage with comprehensive unit and integration tests
• Full type hints with Pydantic validation
• Semantic exceptions for better error handling
• Type-safe enums for IDE autocomplete

Developer Experience

• Query builder pattern with method chaining
• Automatic pagination via .iterate() and .get_all()
• Context manager support for resource cleanup
• Environment variable support (IFPA_API_KEY)

Installation

pip install ifpa-api

Requires Python 3.11 or higher.

Quick Start

from ifpa_api import IFPAClient

# Initialize client
client = IFPAClient()

# Get top 10 ranked players
rankings = client.get_player_rankings(count=10)

# Search for players by name
players = client.search_players(name="John")

# Get tournament details
tournament = client.get_tournament(tournament_id=12345)

# Query builder with method chaining
results = (
    client.tournaments
    .filter(country="USA", state="CA")
    .sort_by("date", descending=True)
    .get_all()
)

Pagination Made Easy

# Memory-efficient iteration over large result sets
for player in client.players.iterate(query="smith"):
    print(f"{player.name}: Rank #{player.wppr_rank}")

# Or get all results at once
all_results = client.tournaments.filter(year=2024).get_all()

Use Cases

• Building pinball statistics dashboards
• Tournament management tools
• Player tracking applications
• Historical data analysis
• Community leaderboards
• Fantasy pinball leagues

Technical Stack

• Language: Python 3.11+
• Validation: Pydantic for request/response models
• HTTP Client: Built-in with context manager support
• Code Quality: Black formatting, comprehensive type hints
• Documentation: GitHub Pages hosted

Links

• PyPI: https://pypi.org/project/ifpa-api/
• Documentation: https://johnsosoka.github.io/ifpa-api-python/
• GitHub: https://github.com/johnsosoka/ifpa-api-python

This library demonstrates professional Python development practices including type safety, comprehensive testing, and thoughtful API design. It’s actively maintained and used by pinball communities worldwide for tournament organization and player statistics tracking.