TFRRS APItfrrs.org ↗

"""
TFRRS Track and Field Results API Client
Practical usage example for extracting college track and field results.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the TFRRS Track and Field Results API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API 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 = "1b66c7cb-769a-4301-82ff-8d308afee7ad"
        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 a request to the Parse API.

        Args:
            endpoint: The API endpoint name
            method: HTTP method (GET or POST)
            **params: Query/body parameters

        Returns:
            Response data from the API
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        else:  # POST
            response = requests.post(url, headers=headers, json=params)

        response.raise_for_status()
        return response.json()

    def search_athlete(self, query: str) -> Dict[str, Any]:
        """
        Search for college athletes by name on TFRRS.

        Args:
            query: Athlete name to search for

        Returns:
            Dictionary with athletes array containing matching athletes
        """
        return self._call("search_athlete", method="GET", query=query)

    def get_athlete_results(self, athlete_id: str) -> Dict[str, Any]:
        """
        Get detailed performance results for a specific college athlete.

        Args:
            athlete_id: Numeric athlete ID from TFRRS

        Returns:
            Dictionary with athlete details, personal bests, and performance history
        """
        return self._call("get_athlete_results", method="GET", athlete_id=athlete_id)

    def get_meet_results(self, meet_id: str) -> Dict[str, Any]:
        """
        Get basic information and event listings for a specific college meet.

        Args:
            meet_id: Numeric meet ID from TFRRS

        Returns:
            Dictionary with meet info, events list, and partial athlete list
        """
        return self._call("get_meet_results", method="GET", meet_id=meet_id)

    def get_event_results(self, event_url: str) -> Dict[str, Any]:
        """
        Get results for a specific event within a meet.

        Args:
            event_url: Full URL of the event results page

        Returns:
            Dictionary with results array containing placements and marks
        """
        return self._call("get_event_results", method="GET", event_url=event_url)

    def get_team_roster(self, team_url: str) -> Dict[str, Any]:
        """
        Get the roster of athletes for a specific college team.

        Args:
            team_url: Path or full URL of the team page

        Returns:
            Dictionary with team name and roster of athletes
        """
        return self._call("get_team_roster", method="GET", team_url=team_url)


def main():
    """
    Practical workflow example: Find an athlete, get their results, and analyze their performance.
    """
    # Initialize the client
    client = ParseClient()

    print("=" * 60)
    print("TFRRS Track and Field Results - Analysis Example")
    print("=" * 60)

    # Step 1: Search for an athlete
    print("\n[Step 1] Searching for athlete: 'Graham Blanks'")
    search_response = client.search_athlete("Graham Blanks")

    if "data" in search_response and search_response["data"]["athletes"]:
        athletes = search_response["data"]["athletes"]
        print(f"Found {len(athletes)} athlete(s)")

        # Step 2: Get details for the first matching athlete
        athlete = athletes[0]
        athlete_id = athlete["athlete_id"]
        print(f"\n[Step 2] Getting results for {athlete['name']} (ID: {athlete_id})")

        athlete_results = client.get_athlete_results(athlete_id)

        # Extract and display athlete information
        if "data" in athlete_results:
            athlete_data = athlete_results["data"]
            print(f"\nAthlete: {athlete_data['name']}")
            print(f"Team: {athlete_data['team']}")
            if athlete_data.get("year"):
                print(f"Year: {athlete_data['year']}")

            # Step 3: Display personal bests
            print(f"\nPersonal Bests:")
            if athlete_data.get("personal_bests"):
                for pb in athlete_data["personal_bests"]:
                    print(f"  {pb['event']:20s}: {pb['mark']}")
            else:
                print("  No personal bests available")

            # Step 4: Display recent performances
            print(f"\nRecent Performances (last 10):")
            performances = athlete_data.get("performances", [])
            for perf in performances[:10]:
                event_type = "XC" if perf.get("is_xc") else "Track/Field"
                print(f"  {perf['meet_date']:20s} | {perf['event']:10s} | {perf['mark']:12s} | Place: {perf['place']:5s} | {event_type}")

            # Step 5: Get team roster to see teammates
            print(f"\n[Step 3] Getting team roster for {athlete_data['team']}")
            team_name = athlete_data['team']
            state_code = "MA"  # Harvard is in Massachusetts
            team_url = f"/teams/tf/{state_code}_college_m_{team_name.lower()}.html"

            try:
                roster_response = client.get_team_roster(team_url)
                if "data" in roster_response:
                    roster_data = roster_response["data"]
                    print(f"\n{roster_data['team_name']} Roster ({len(roster_data['roster'])} athletes):")
                    for i, teammate in enumerate(roster_data["roster"][:5], 1):
                        print(f"  {i}. {teammate['name']} (ID: {teammate['athlete_id']})")
                    if len(roster_data["roster"]) > 5:
                        print(f"  ... and {len(roster_data['roster']) - 5} more athletes")
            except Exception as e:
                print(f"Note: Could not retrieve team roster: {e}")

    else:
        print("No athletes found matching the search query")

    print("\n" + "=" * 60)
    print("Analysis complete!")
    print("=" * 60)


if __name__ == "__main__":
    main()