Qzz APItraceodds.qzz.io ↗

"""
TraceOdds AI Betting Analysis API Client

This module provides a client for accessing AI-powered sports betting analysis
from TraceOdds, including upcoming match fixtures, historical betting picks, and
detailed match analysis reports.

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

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


class ParseClient:
    """Client for interacting with the TraceOdds AI Betting Analysis API."""
    
    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 environment variable.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "35190916-a0c4-442c-8cb9-163a5f699ca3"
        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 an API call to the Parse bot.
        
        Args:
            endpoint: The endpoint name to call
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to send with the request
            
        Returns:
            Response JSON as dictionary
            
        Raises:
            requests.RequestException: If the API call 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)
        elif method.upper() == "POST":
            payload = params if params else {}
            response = requests.post(url, headers=headers, json=payload)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()
    
    def get_fixtures(self) -> Dict[str, Any]:
        """
        Get upcoming match fixtures across all tracked leagues.
        
        Returns upcoming fixtures for approximately the next 7 days with
        AI-computed value index, stability index, recommended picks, odds,
        hit rates, and expected value.
        
        Returns:
            Dictionary containing 'fixtures' array and 'total' count
        """
        return self._call("get_fixtures", method="GET")
    
    def get_picks(self) -> Dict[str, Any]:
        """
        Get current bankroll stats and recent betting history.
        
        Returns the current bankroll statistics and recent betting history
        (last ~50 picks) with match details, bet specifics, confidence scores,
        results, and profit/loss amounts.
        
        Returns:
            Dictionary containing 'stats', 'history', and 'history_count'
        """
        return self._call("get_picks", method="GET")
    
    def get_match_report(self, match_id: str, league_key: str) -> Dict[str, Any]:
        """
        Get detailed AI analysis report for a specific match.
        
        Provides comprehensive AI analysis including Dixon-Coles model
        predictions, expected goals, BTTS probability, EV calculations,
        main pick recommendation, and pre-match intelligence.
        
        Args:
            match_id: Pipe-separated lowercase team names (e.g., 'spain|cape_verde')
            league_key: League identifier key (e.g., 'soccer_fifa_world_cup')
            
        Returns:
            Dictionary containing detailed match analysis
        """
        return self._call(
            "get_match_report",
            method="GET",
            match_id=match_id,
            league_key=league_key
        )


def format_currency(value: str) -> str:
    """Format currency string for display."""
    return value if isinstance(value, str) else f"${value}"


def print_bankroll_summary(stats: Dict[str, str]) -> None:
    """Print formatted bankroll summary."""
    print("\n" + "=" * 60)
    print("💰 BANKROLL SUMMARY")
    print("=" * 60)
    print(f"Current Bankroll: {stats['bankroll']}")
    print(f"Total P&L: {stats['total_pnl']}")
    print(f"Win/Loss Record: {stats['win_loss']}")
    print(f"Unit Size: {stats['unit_size']}")


def print_fixture(fixture: Dict[str, Any]) -> None:
    """Print formatted fixture information."""
    print(f"\n🎯 {fixture['label']}")
    print(f"   League: {fixture['league']}")
    print(f"   Kickoff: {fixture['commence']}")
    print(f"   Pick: {fixture['pick']} @ {fixture['odds']}")
    print(f"   Value Index: {fixture['value_index']} | Stability: {fixture['stability_index']}")
    print(f"   Expected Value: {fixture['ev']:+.2%} | Hit Rate: {fixture['hit_rate']}%")


def print_match_report_summary(report: Dict[str, Any]) -> None:
    """Print formatted match report summary."""
    print("\n" + "=" * 60)
    print(f"📊 {report['match']} - {report['league']}")
    print("=" * 60)
    print(f"Kickoff: {report['kickoff_info']}")
    print(f"\n📈 Model Analysis:")
    print(f"   Main Pick: {report['main_pick']}")
    print(f"   Win Rate: {report['model_win_rate']}%")
    print(f"   Expected Value: {report['ev_percent']:+.1f}%")
    print(f"\n⚽ Match Predictions:")
    print(f"   Home Expected Goals: {report['home_expected_goals']:.2f}")
    print(f"   Away Expected Goals: {report['away_expected_goals']:.2f}")
    print(f"   BTTS Probability: {report['btts_percent']}%")
    print(f"   Over 2.5 Goals: {report['over_2_5_percent']}%")
    print(f"\n📝 Summary:\n{report['summary']}")


def main():
    """
    Practical workflow example: Analyze upcoming fixtures and generate reports.
    
    This workflow:
    1. Fetches upcoming fixtures
    2. Reviews current bankroll and recent picks
    3. Gets detailed analysis for top-value fixtures
    4. Displays actionable betting recommendations
    """
    
    # Initialize client
    client = ParseClient()
    print("🚀 TraceOdds AI Betting Analysis - Practical Example")
    print("=" * 60)
    
    # Step 1: Get current bankroll and recent picks
    print("\n📊 Fetching current bankroll and recent picks...")
    picks_data = client.get_picks()
    print_bankroll_summary(picks_data["stats"])
    
    # Display recent picks summary
    print(f"\n📋 Recent Picks Summary ({picks_data['history_count']} total):")
    for pick in picks_data["history"][:5]:  # Show last 5 picks
        status = "✅" if pick["result"] == "赢一半" else "❌"
        print(
            f"   {status} {pick['date']}: {pick['match']} "
            f"→ {pick['bet_detail']} (Confidence: {pick['confidence']}%) "
            f"Result: {pick['result']} P&L: {pick['pnl']}"
        )
    
    # Step 2: Get upcoming fixtures
    print("\n\n🔍 Fetching upcoming fixtures...")
    fixtures_data = client.get_fixtures()
    total_fixtures = fixtures_data["total"]
    print(f"Found {total_fixtures} upcoming fixtures")
    
    # Filter and sort fixtures by value index (high value = best opportunities)
    high_value_fixtures = sorted(
        fixtures_data["fixtures"],
        key=lambda x: x["value_index"],
        reverse=True
    )[:5]  # Top 5 by value
    
    print(f"\n🌟 Top 5 Highest Value Fixtures:")
    for fixture in high_value_fixtures:
        print_fixture(fixture)
    
    # Step 3: Get detailed reports for top 2 fixtures
    print("\n\n📈 Generating detailed analysis for top 2 fixtures...")
    for fixture in high_value_fixtures[:2]:
        try:
            # Extract match_id and league_key from fixture
            match_id = fixture["id"]
            league_key = fixture["league_key"]
            
            print(f"\n⏳ Analyzing {fixture['label']}...")
            report = client.get_match_report(match_id, league_key)
            print_match_report_summary(report)
            
        except requests.RequestException as e:
            print(f"   ⚠️  Could not fetch report: {e}")
        except KeyError as e:
            print(f"   ⚠️  Missing data field: {e}")
    
    # Step 4: Summary and recommendations
    print("\n\n" + "=" * 60)
    print("📌 BETTING RECOMMENDATIONS SUMMARY")
    print("=" * 60)
    print(f"\n✨ Next Action Items:")
    print(f"   1. Current Bankroll: {picks_data['stats']['bankroll']}")
    print(f"   2. Review top 5 fixtures above for high-value opportunities")
    print(f"   3. Focus on picks with Value Index > 80 and Stability > 60")
    print(f"   4. Average unit size: {picks_data['stats']['unit_size']}")
    print(f"\n💡 Pro Tip: Combine high value index with high stability for")
    print(f"   more consistent returns. Monitor EV percentages closely.")
    print("=" * 60)


if __name__ == "__main__":
    main()