USATF APIresults.usatf.org ↗

"""
USATF Results API Client

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

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


class ParseClient:
    """Client for interacting with USATF Results API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse client.

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "a50746f4-55bb-4edb-8907-4da8934f2c19"
        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 scraper.

        Args:
            endpoint: The endpoint name to call
            method: HTTP method (GET or POST)
            **params: Parameters to pass to the endpoint

        Returns:
            The JSON response from the API

        Raises:
            requests.RequestException: If the API call fails
            ValueError: If the response indicates an error
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

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

            response.raise_for_status()
            result = response.json()

            if result.get("status") != "success":
                raise ValueError(f"API error: {result.get('error', 'Unknown error')}")

            return result.get("data", {})
        except requests.RequestException as e:
            raise requests.RequestException(f"API call failed: {e}")

    def get_competition_info(self, meet_id: str = "8035") -> Dict[str, Any]:
        """
        Get top-level metadata about a USATF competition.

        Args:
            meet_id: Meet ID (default: '8035' for 2025 Toyota USATF Outdoor Championships)

        Returns:
            Competition metadata including name, facility, location, dates
        """
        return self._call("get_competition_info", method="GET", meet_id=meet_id)

    def get_schedule_by_day(self, meet_id: str = "8035", date: Optional[str] = None) -> Dict[str, Any]:
        """
        Get the event schedule for a competition, optionally filtered by date.

        Args:
            meet_id: Meet ID (default: '8035')
            date: Optional date filter in ISO format YYYY-MM-DD (e.g., '2025-08-02')

        Returns:
            Dictionary containing 'events' array with scheduled events
        """
        params = {"meet_id": meet_id}
        if date:
            params["date"] = date
        return self._call("get_schedule_by_day", method="GET", **params)

    def get_event_results(self, event_key: str, meet_id: str = "8035") -> Dict[str, Any]:
        """
        Get detailed results and athlete entries for a specific event.

        Args:
            event_key: Event key in format 'EN-R' (e.g., '22-1', '3-1')
            meet_id: Meet ID (default: '8035')

        Returns:
            Event results including athlete entries with names, marks, placements
        """
        return self._call("get_event_results", method="GET", meet_id=meet_id, event_key=event_key)

    def get_athlete_profile(self, athlete_id: str, meet_id: str = "8035") -> Dict[str, Any]:
        """
        Get full biography and competition history for an athlete.

        Args:
            athlete_id: Athlete ID (obtainable from event results)
            meet_id: Meet ID context (default: '8035')

        Returns:
            Athlete profile with biographical data, honors, and personal bests
        """
        return self._call("get_athlete_profile", method="GET", meet_id=meet_id, athlete_id=athlete_id)

    def get_para_nationals_schedule_by_day(self, date: Optional[str] = None) -> Dict[str, Any]:
        """
        Get the event schedule for the 2025 Para Nationals (meet ID 8036).

        Args:
            date: Optional date filter in ISO format YYYY-MM-DD

        Returns:
            Dictionary containing 'events' array for Para Nationals
        """
        params = {}
        if date:
            params["date"] = date
        return self._call("get_para_nationals_schedule_by_day", method="GET", **params)


def print_section(title: str) -> None:
    """Print a formatted section header."""
    print(f"\n{'='*60}")
    print(f"  {title}")
    print(f"{'='*60}\n")


if __name__ == "__main__":
    # Initialize client
    client = ParseClient()

    # Step 1: Get competition info to understand the event
    print_section("STEP 1: Fetching 2025 Toyota USATF Outdoor Championships Info")
    comp_info = client.get_competition_info(meet_id="8035")
    print(f"Competition: {comp_info['name']}")
    print(f"Facility: {comp_info['facility']}")
    print(f"Location: {comp_info['location']}")
    print(f"Dates: {comp_info['startDate']} to {comp_info['endDate']}")

    # Step 2: Get schedule for a specific date
    print_section("STEP 2: Fetching Schedule for August 2, 2025")
    schedule = client.get_schedule_by_day(meet_id="8035", date="2025-08-02")
    events = schedule.get("events", [])
    print(f"Found {len(events)} events on this date:\n")

    # Display first 5 events
    for event in events[:5]:
        print(f"  • {event['N']}")
        print(f"    Round: {event['RN']}, Status: {event['S']}")
        print(f"    Time: {event['T']}, Gender: {event['G']}")
        print(f"    Event Key: {event['event_key']}\n")

    # Step 3: Get results from a specific event (Women's 20K Racewalk)
    if events:
        # Find an event with complete results
        target_event = next((e for e in events if e['S'] == 'Complete'), events[0])
        event_key = target_event['event_key']
        print_section(f"STEP 3: Fetching Results for {target_event['N']}")
        results = client.get_event_results(event_key=event_key, meet_id="8035")

        print(f"Event: {results['N']}")
        print(f"Round: {results['RN']}")
        print(f"Status: {results['S']}\n")

        # Extract and display athlete results
        athlete_entries = results.get("ED", {})
        print(f"Top 3 Finishers:\n")

        # Sort by placement and get top finishers
        sorted_athletes = sorted(
            athlete_entries.items(),
            key=lambda x: int(x[1].get('P', 999))
        )

        for entry_id, entry_data in sorted_athletes[:3]:
            athlete = entry_data.get("A", {})
            name = athlete.get("N", "Unknown")
            mark = entry_data.get("M", "N/A")
            place = entry_data.get("P", "N/A")
            team = entry_data.get("TN", "N/A")
            athlete_id = athlete.get("ID")

            print(f"  {place}. {name}")
            print(f"     Time: {mark}, Team: {team}")
            print(f"     Athlete ID: {athlete_id}\n")

            # Step 4: Get detailed profile for top finisher (only for first place)
            if place == 1 and athlete_id:
                print_section(f"STEP 4: Fetching Athlete Profile for {name}")
                try:
                    profile = client.get_athlete_profile(athlete_id=str(athlete_id), meet_id="8035")
                    basic = profile.get("basicData", {})
                    print(f"Name: {basic.get('givenName')} {basic.get('familyName')}")
                    print(f"Country: {basic.get('countryCode')}")
                    print(f"Birth Date: {basic.get('birthDate')}")
                    print(f"Affiliation: {basic.get('affiliation')}")

                    # Display honours/major achievements
                    honours = profile.get("honours", [])
                    if honours:
                        print(f"\nMajor Honours:")
                        for honour in honours[:2]:
                            category = honour.get("categoryName", "Unknown")
                            results_list = honour.get("results", [])
                            if results_list:
                                print(f"  • {category}:")
                                for result in results_list[:1]:
                                    print(f"    - {result.get('discipline')}: {result.get('mark')} ({result.get('place')})")

                    # Display personal bests
                    pb = profile.get("personalBests", {})
                    pb_results = pb.get("results", [])
                    if pb_results:
                        print(f"\nPersonal Bests:")
                        for pb_entry in pb_results[:2]:
                            print(f"  • {pb_entry.get('discipline')}: {pb_entry.get('mark')}")

                except ValueError as e:
                    print(f"Note: Could not fetch full profile - {e}")

    # Step 5: Bonus - Check Para Nationals schedule
    print_section("STEP 5: Checking Para Nationals Schedule (August 2)")
    para_schedule = client.get_para_nationals_schedule_by_day(date="2025-08-02")
    para_events = para_schedule.get("events", [])
    print(f"Found {len(para_events)} Para Nationals events on August 2:\n")

    for event in para_events[:3]:
        print(f"  • {event['N']}")
        print(f"    Round: {event['RN']}, Status: {event['S']}")
        print(f"    Time: {event['T']}\n")

    print_section("WORKFLOW COMPLETE")
    print("Successfully demonstrated:")
    print("  1. Fetching competition metadata")
    print("  2. Getting event schedules by date")
    print("  3. Retrieving detailed event results")
    print("  4. Accessing athlete profile data")
    print("  5. Exploring Para Nationals events")