Gamescom APIexhibitors.gamescom.global ↗

"""
Gamescom 2025 Exhibitor API Client
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Gamescom 2025 Exhibitor API."""
    
    def __init__(self, api_key: Optional[str] = None):
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "49abfa19-80cb-4234-b5bf-f7cc93621be9"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key not provided and PARSE_API_KEY environment variable not set")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """Make an API call to the Parse bot."""
        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":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()
    
    def list_exhibitors(
        self,
        letter: Optional[str] = None,
        start: int = 0,
        product_group: Optional[str] = None,
        country: Optional[str] = None,
        hall: Optional[str] = None,
        query: Optional[str] = None,
        limit: int = 20
    ) -> Dict[str, Any]:
        """
        Retrieve the full paginated list of exhibitors.
        
        Args:
            letter: Initial letter filter (e.g., 'A')
            start: Starting offset for pagination (default: 0)
            product_group: Product group ID filter
            country: ISO 3166-1 alpha-2 country code (e.g., 'DE')
            hall: Hall filter (e.g., '3.2')
            query: Search keyword
            limit: Max results to return (default: 20)
        
        Returns:
            Dictionary containing exhibitors list and next_start for pagination
        """
        params = {
            "start": start,
            "limit": limit
        }
        if letter:
            params["letter"] = letter
        if product_group:
            params["product_group"] = product_group
        if country:
            params["country"] = country
        if hall:
            params["hall"] = hall
        if query:
            params["query"] = query
        
        return self._call("list_exhibitors", method="GET", **params)
    
    def search_exhibitors(
        self,
        query: str,
        country: Optional[str] = None,
        product_group: Optional[str] = None,
        hall: Optional[str] = None,
        limit: int = 20
    ) -> Dict[str, Any]:
        """
        Search and filter exhibitors using keyword and categories.
        
        Args:
            query: Search keyword (required)
            country: ISO 3166-1 alpha-2 country code filter
            product_group: Product group ID
            hall: Hall filter
            limit: Max results to return (default: 20)
        
        Returns:
            Dictionary containing search results and pagination info
        """
        params = {
            "query": query,
            "limit": limit
        }
        if country:
            params["country"] = country
        if product_group:
            params["product_group"] = product_group
        if hall:
            params["hall"] = hall
        
        return self._call("search_exhibitors", method="GET", **params)
    
    def get_exhibitor_detail(self, slug: str) -> Dict[str, Any]:
        """
        Retrieve full details for a specific exhibitor.
        
        Args:
            slug: Exhibitor slug from list or search endpoints
        
        Returns:
            Dictionary containing exhibitor details including website and address
        """
        return self._call("get_exhibitor_detail", method="GET", slug=slug)
    
    def list_product_groups(self) -> Dict[str, Any]:
        """
        Retrieve the full list of product categories (product groups).
        
        Returns:
            Dictionary containing product_groups array with id, name, and count
        """
        return self._call("list_product_groups", method="GET")


def main():
    """
    Demonstrate a practical workflow using the Gamescom Exhibitor API.
    
    This example shows how to:
    1. Get all product categories
    2. Find a specific category
    3. Search for exhibitors in that category
    4. Fetch detailed information for each result
    5. Present organized information about exhibitors
    """
    
    client = ParseClient()
    
    print("=" * 80)
    print("GAMESCOM 2025 - EXHIBITOR DISCOVERY WORKFLOW")
    print("=" * 80)
    
    # Step 1: Retrieve all product categories
    print("\n[STEP 1] Fetching available product categories...")
    try:
        product_groups_response = client.list_product_groups()
        product_groups = product_groups_response.get("data", {}).get("product_groups", [])
        print(f"✓ Found {len(product_groups)} product categories")
        
        # Display first few categories
        print("\nAvailable categories:")
        for group in product_groups[:5]:
            print(f"  • {group['name']} (ID: {group['id']}, Exhibitors: {group['count']})")
        if len(product_groups) > 5:
            print(f"  ... and {len(product_groups) - 5} more categories")
    except Exception as e:
        print(f"✗ Failed to fetch product groups: {e}")
        return
    
    # Step 2: Search for specific exhibitors
    print("\n[STEP 2] Searching for exhibitors with 'game' keyword...")
    try:
        search_response = client.search_exhibitors(query="game", limit=10)
        exhibitors = search_response.get("data", {}).get("exhibitors", [])
        print(f"✓ Found {len(exhibitors)} exhibitors matching 'game'")
        
        if not exhibitors:
            print("No exhibitors found for this search.")
            return
        
        # Display search results summary
        print("\nSearch results:")
        for idx, exhibitor in enumerate(exhibitors[:3], 1):
            print(f"  {idx}. {exhibitor['name']}")
            print(f"     Country: {exhibitor['country']}")
            print(f"     Booth: {exhibitor['booth_info']}")
    except Exception as e:
        print(f"✗ Failed to search exhibitors: {e}")
        return
    
    # Step 3: Get detailed information for top results
    print("\n[STEP 3] Fetching detailed information for top 3 exhibitors...")
    detailed_results = []
    
    for idx, exhibitor in enumerate(exhibitors[:3], 1):
        slug = exhibitor.get("slug")
        name = exhibitor.get("name", "Unknown")
        
        if not slug:
            print(f"  [{idx}] Skipping {name} - no slug available")
            continue
        
        try:
            print(f"  [{idx}] Fetching details for '{name}'...")
            detail = client.get_exhibitor_detail(slug)
            detailed_results.append(detail.get("data", {}))
            print(f"      ✓ Details retrieved successfully")
        except Exception as e:
            print(f"      ✗ Failed to fetch details: {e}")
    
    # Step 4: Display comprehensive exhibitor information
    if detailed_results:
        print("\n" + "=" * 80)
        print("DETAILED EXHIBITOR INFORMATION")
        print("=" * 80)
        
        for idx, exhibitor in enumerate(detailed_results, 1):
            print(f"\n[{idx}] {exhibitor.get('name', 'N/A')}")
            print("-" * 80)
            
            # Website
            website = exhibitor.get('website', 'N/A')
            if website and website != 'N/A':
                print(f"    Website: {website}")
            
            # Address
            address = exhibitor.get('address', 'N/A')
            if address and address != 'N/A':
                print(f"    Address: {address}")
            
            # Hall and Booth
            hall_booth = exhibitor.get('hall_booth', 'N/A')
            if hall_booth and hall_booth != 'N/A':
                print(f"    Hall & Booth: {hall_booth}")
            
            # Product Groups
            product_groups_list = exhibitor.get('product_groups', [])
            if product_groups_list:
                print(f"    Product Groups:")
                for pg in product_groups_list[:4]:
                    print(f"      • {pg}")
                if len(product_groups_list) > 4:
                    print(f"      ... and {len(product_groups_list) - 4} more")
            
            # Represented At
            represented_at = exhibitor.get('represented_at')
            if represented_at:
                print(f"    Note: {represented_at}")
    
    # Step 5: Browse exhibitors by starting letter
    print("\n[STEP 4] Browsing exhibitors by starting letter 'G'...")
    try:
        list_response = client.list_exhibitors(letter="G", limit=8)
        exhibitors_by_letter = list_response.get("data", {}).get("exhibitors", [])
        print(f"✓ Found {len(exhibitors_by_letter)} exhibitors starting with 'G'")
        
        if exhibitors_by_letter:
            print("\nExhibitors starting with 'G':")
            for idx, exhibitor in enumerate(exhibitors_by_letter[:5], 1):
                print(f"  {idx}. {exhibitor['name']} ({exhibitor['country']})")
                print(f"     Booth: {exhibitor['booth_info']}")
        
        # Check for pagination
        next_start = list_response.get("data", {}).get("next_start")
        if next_start is not None:
            print(f"\n  → More exhibitors available at offset: {next_start}")
    except Exception as e:
        print(f"✗ Failed to list exhibitors: {e}")
    
    # Step 6: Filter by country
    print("\n[STEP 5] Searching for German exhibitors...")
    try:
        country_response = client.list_exhibitors(country="DE", limit=5)
        de_exhibitors = country_response.get("data", {}).get("exhibitors", [])
        print(f"✓ Found {len(de_exhibitors)} exhibitors from Germany")
        
        if de_exhibitors:
            print("\nGerman exhibitors (sample):")
            for exhibitor in de_exhibitors[:3]:
                print(f"  • {exhibitor['name']} - {exhibitor['booth_info']}")
    except Exception as e:
        print(f"✗ Failed to filter by country: {e}")
    
    print("\n" + "=" * 80)
    print("WORKFLOW COMPLETED SUCCESSFULLY")
    print("=" * 80)


if __name__ == "__main__":
    main()