World Athletics APIWorldAthletics.org ↗

"""
World Athletics API Client

This module provides a Python client for interacting with the World Athletics API
through Parse. Search for athletes, retrieve their competition results, and access
their career history from major championships.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Dict, Any


class ParseClient:
    """Client for interacting with World Athletics API through Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse client with API credentials."""
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "c818b331-d34b-4d51-b08b-f72111010743"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """Make an API call to the Parse endpoint."""
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_athletes(
        self,
        query: str,
        gender: Optional[str] = None,
        discipline_code: Optional[str] = None,
        country_code: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Search for athletes by name.
        
        Args:
            query: Athlete name or partial name to search for (e.g. 'Bolt', 'Hassan')
            gender: Optional filter by gender
            discipline_code: Optional filter by discipline code
            country_code: Optional filter by 3-letter country code (e.g. 'JAM', 'USA')
            
        Returns:
            Dictionary containing athletes list and total count
        """
        params = {"query": query}
        if gender:
            params["gender"] = gender
        if discipline_code:
            params["discipline_code"] = discipline_code
        if country_code:
            params["country_code"] = country_code
            
        return self._call("search_athletes", method="GET", **params)

    def get_athlete_results(
        self,
        athlete_id: str,
        year: Optional[int] = None
    ) -> Dict[str, Any]:
        """
        Get competition results for an athlete in a specific year.
        
        Args:
            athlete_id: Numeric athlete ID from search results
            year: Optional year to retrieve results for (defaults to most recent)
            
        Returns:
            Dictionary containing active years and results by event
        """
        params = {"athlete_id": athlete_id}
        if year:
            params["year"] = year
            
        return self._call("get_athlete_results", method="GET", **params)

    def get_athlete_career(
        self,
        athlete_id: str,
        url_slug: str
    ) -> Dict[str, Any]:
        """
        Get major championship results (career history) for an athlete.
        
        Args:
            athlete_id: Numeric athlete ID from search results
            url_slug: Athlete URL slug from search results
            
        Returns:
            Dictionary containing career results organized by competition category
        """
        return self._call(
            "get_athlete_career",
            method="GET",
            athlete_id=athlete_id,
            url_slug=url_slug
        )

    def get_athlete_profile(
        self,
        athlete_id: str,
        url_slug: str
    ) -> Dict[str, Any]:
        """
        Get an athlete's full profile including biographical data, personal bests, and achievements.
        
        Args:
            athlete_id: Numeric athlete ID from search results
            url_slug: Athlete URL slug from search results
            
        Returns:
            Dictionary containing complete athlete profile with honours and world rankings
        """
        return self._call(
            "get_athlete_profile",
            method="GET",
            athlete_id=athlete_id,
            url_slug=url_slug
        )


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()
    
    print("=" * 70)
    print("World Athletics API - Practical Usage Example")
    print("=" * 70)
    
    # Step 1: Search for distance runners
    print("\n📍 Step 1: Searching for elite marathon runners...")
    search_results = client.search_athletes("Kipchoge")
    
    athletes = search_results.get("athletes", [])
    total = search_results.get("total", 0)
    
    print(f"   Found {total} total results (displaying {len(athletes)} results)")
    
    if not athletes:
        print("   No athletes found with that search. Trying alternative search...")
        search_results = client.search_athletes("Hassan", country_code="ETH")
        athletes = search_results.get("athletes", [])
    
    # Step 2: Analyze each athlete found
    for athlete_idx, athlete in enumerate(athletes[:2], 1):
        athlete_id = athlete["athlete_id"]
        url_slug = athlete["url_slug"]
        given_name = athlete["given_name"]
        family_name = athlete["family_name"]
        country = athlete["country"]
        disciplines = athlete["disciplines"]
        birth_date = athlete["birth_date"]
        
        print(f"\n{'=' * 70}")
        print(f"Athlete {athlete_idx}: {given_name} {family_name}")
        print(f"{'=' * 70}")
        print(f"   Country: {country}")
        print(f"   Birth Date: {birth_date}")
        print(f"   Disciplines: {disciplines}")
        print(f"   ID: {athlete_id}")
        
        # Step 3: Get recent competition results (2023)
        print(f"\n   📊 Fetching 2023 competition results...")
        try:
            results_data = client.get_athlete_results(athlete_id, year=2023)
            
            active_years = results_data.get("active_years", [])
            year_displayed = results_data.get("year")
            results_by_event = results_data.get("results_by_event", [])
            
            if active_years:
                print(f"   Active years: {', '.join(active_years[:8])}")
            
            if results_by_event:
                print(f"   Results in {year_displayed or 'most recent year'} ({len(results_by_event)} disciplines):")
                
                for event in results_by_event[:3]:
                    discipline = event.get("discipline", "Unknown")
                    results = event.get("results", [])
                    
                    if results:
                        print(f"\n      🏃 {discipline}:")
                        for result in results[:2]:
                            mark = result.get("mark", "N/A")
                            place = result.get("place", "N/A")
                            venue = result.get("venue", "Unknown")
                            date = result.get("date", "N/A")
                            competition = result.get("competition", "Unknown")
                            
                            print(f"         • {mark} ({place}) at {competition}")
                            print(f"           Venue: {venue} | Date: {date}")
                        
                        if len(results) > 2:
                            print(f"         ... and {len(results) - 2} more races")
            else:
                print(f"   No results found for {year_displayed or 'the selected year'}")
        except Exception as e:
            print(f"   ⚠️  Could not fetch recent results: {e}")
        
        # Step 4: Get career achievements
        print(f"\n   🏆 Fetching career achievements...")
        try:
            career_data = client.get_athlete_career(athlete_id, url_slug)
            career_results = career_data.get("career_results", [])
            
            for category in career_results:
                category_name = category.get("category", "Unknown")
                results = category.get("results", [])
                
                if results:
                    print(f"\n      {category_name} ({len(results)} results):")
                    for result in results[:2]:
                        discipline = result.get("discipline", "Unknown")
                        competition = result.get("competition", "Unknown")
                        place = result.get("place", "N/A")
                        result_mark = result.get("result", "N/A")
                        date = result.get("date", "N/A")
                        venue = result.get("venue", "Unknown")
                        
                        print(f"         • {discipline}: {result_mark}")
                        print(f"           {competition} ({place})")
                        print(f"           {venue} | {date}")
                    
                    if len(results) > 2:
                        print(f"         ... and {len(results) - 2} more achievements")
        except Exception as e:
            print(f"   ⚠️  Could not fetch career data: {e}")
        
        # Step 5: Get full athlete profile
        print(f"\n   👤 Fetching complete athlete profile...")
        try:
            profile_data = client.get_athlete_profile(athlete_id, url_slug).get("data", {})
            
            country_name = profile_data.get("country_name", "Unknown")
            iaaf_id = profile_data.get("iaaf_id")
            biography = profile_data.get("biography")
            
            print(f"      Country: {country_name}")
            if iaaf_id:
                print(f"      IAAF ID: {iaaf_id}")
            
            # Display personal bests
            personal_bests = profile_data.get("personal_bests", [])
            if personal_bests:
                print(f"\n      Personal Bests ({len(personal_bests)} disciplines):")
                for pb in personal_bests[:3]:
                    discipline = pb.get("discipline", "Unknown")
                    mark = pb.get("mark", "N/A")
                    venue = pb.get("venue", "Unknown")
                    date = pb.get("date", "N/A")
                    
                    print(f"         • {discipline}: {mark}")
                    print(f"           {venue} ({date})")
                
                if len(personal_bests) > 3:
                    print(f"         ... and {len(personal_bests) - 3} more personal bests")
            
            # Display world rankings
            world_rankings = profile_data.get("world_rankings", {})
            current_rankings = world_rankings.get("current", [])
            
            if current_rankings:
                print(f"\n      Current World Rankings:")
                for ranking in current_rankings[:3]:
                    event_group = ranking.get("event_group", "Unknown")
                    place = ranking.get("place", "N/A")
                    
                    print(f"         • {event_group}: #{place}")
        except Exception as e:
            print(f"   ⚠️  Could not fetch profile: {e}")
    
    print(f"\n{'=' * 70}")
    print("✅ Example completed successfully!")
    print("=" * 70)