HLLRecords APIhllrecords.com ↗

"""
HLLRecords Player Data API Client

This module provides a Python client for searching and retrieving Hell Let Loose
player combat records and statistics from HLLRecords.com via the Parse API.

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

import os
import requests
from typing import Optional, Any


class ParseClient:
    """Client for interacting with the HLLRecords Player Data 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, will use PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "2d54c33e-03d9-4f5e-9ebe-571b6c0de49c"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

    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 (e.g., 'search_players')
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to send with the request

        Returns:
            JSON response from the API

        Raises:
            requests.exceptions.RequestException: If the request fails
        """
        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, timeout=30)
        elif method.upper() == "POST":
            payload = params if params else {}
            response = requests.post(url, headers=headers, json=payload, timeout=30)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_players(self, query: str) -> dict[str, Any]:
        """Search for Hell Let Loose players by username.

        Args:
            query: Player username or partial username to search for

        Returns:
            Dictionary containing list of matching players and count
        """
        return self._call("search_players", method="GET", query=query)

    def get_player_profile(
        self, player_id: str, period: Optional[str] = None
    ) -> dict[str, Any]:
        """Get detailed player profile including combat statistics.

        Args:
            player_id: Player external ID (Steam ID or hash) from search results
            period: Time period filter ('365d', '180d', '90d', '30d', '2025' or None for lifetime)

        Returns:
            Dictionary containing detailed player profile and statistics
        """
        params = {"player_id": player_id}
        if period:
            params["period"] = period
        return self._call("get_player_profile", method="GET", **params)


def format_player_summary(player: dict[str, Any]) -> str:
    """Format a player search result for display."""
    return f"  • {player['name']} (ID: {player['external_id']}) - Last seen: {player['last_seen']}"


def format_player_stats(profile: dict[str, Any], period_label: str = "Lifetime") -> str:
    """Format player profile statistics for display."""
    playstyle = profile.get("playstyle_stats", {})
    stats = [
        f"\n{'='*60}",
        f"Player: {profile['name']} | Level: {profile['level']}",
        f"Period: {period_label}",
        f"{'='*60}",
        f"Matches Played: {profile['matches_played']}",
        f"Total Time: {profile['total_on_servers']}",
        f"K/D Ratio: {profile['kd_ratio']} | Win Rate: {profile['win_rate']}",
        f"Infantry Kill ELO: {profile['infantry_kill_elo']}",
        f"Enemy Kills: {profile['enemy_kills']} | Total Deaths: {profile['total_deaths']}",
        f"Team Kills: {profile['team_kills']} | Melee: {profile['melee_kills']}",
        f"Faction Preference: {profile['faction_preference']}",
        f"\nPlaystyle Metrics:",
        f"  KPM: {playstyle.get('kpm', 'N/A')} | DPM: {playstyle.get('dpm', 'N/A')} | KDR: {playstyle.get('kdr', 'N/A')}",
        f"  Combat Score: {playstyle.get('combat_score', 'N/A')}/min | Support Score: {playstyle.get('support_score', 'N/A')}/min",
        f"  Defense: {playstyle.get('defense', 'N/A')} | Offense: {playstyle.get('offense', 'N/A')}",
        f"  Duel Strength: {playstyle.get('duel_strength', 'N/A')}",
        f"First Seen: {profile['first_seen']}",
    ]
    return "\n".join(stats)


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

    print("\n" + "="*60)
    print("HLLRecords Player Data Lookup - Competitive Analysis")
    print("="*60)

    # Search for players matching a criteria
    search_query = "soldier"
    print(f"\nSearching for players with username containing '{search_query}'...")

    try:
        search_results = client.search_players(search_query)
        print(f"\n✓ Search complete - Found {search_results['count']} player(s)")

        if search_results["count"] == 0:
            print(f"No players found matching '{search_query}'")
        else:
            print("\nTop Matches:")
            for i, player in enumerate(search_results["players"][:5], 1):
                print(f"{i}. {format_player_summary(player)}")

            print("\n" + "-"*60)
            print("Analyzing top 3 players in detail...")
            print("-"*60)

            # Analyze top 3 players in detail
            for idx, player in enumerate(search_results["players"][:3], 1):
                player_id = player["external_id"]
                player_name = player["name"]

                print(f"\n[{idx}/3] Fetching detailed profile for: {player_name}")

                # Get lifetime stats
                lifetime_profile = client.get_player_profile(player_id)
                print(format_player_stats(lifetime_profile, "Lifetime"))

                # Get recent 30-day stats for comparison
                recent_profile = client.get_player_profile(player_id, period="30d")
                print(format_player_stats(recent_profile, "Last 30 Days"))

                # Compare performance trend
                lifetime_kd = float(lifetime_profile["kd_ratio"])
                recent_kd = float(recent_profile["kd_ratio"])
                trend = "📈 Improving" if recent_kd > lifetime_kd else "📉 Declining" if recent_kd < lifetime_kd else "➡️ Stable"
                print(f"\nTrend Analysis: {trend}")

            print("\n" + "="*60)
            print("Analysis Complete")
            print("="*60 + "\n")

    except requests.exceptions.RequestException as e:
        print(f"❌ Error communicating with API: {e}")
    except KeyError as e:
        print(f"❌ Unexpected API response format: {e}")
    except ValueError as e:
        print(f"❌ Configuration error: {e}")