Testbook APItestbook.com ↗

"""
Testbook Exam Preparation 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 Testbook Exam Preparation API via Parse.bot"""

    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 = "fd84e6b2-7849-4708-adad-1bdac1e30c63"
        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 scraper.
        
        Args:
            endpoint: The API endpoint name (e.g., 'search', 'list_exam_categories')
            method: HTTP method - 'GET' or 'POST'
            **params: Query/request parameters
            
        Returns:
            Response JSON as dictionary
            
        Raises:
            requests.exceptions.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"
        }
        
        try:
            if method.upper() == "GET":
                response = requests.get(url, headers=headers, params=params, timeout=30)
            elif method.upper() == "POST":
                response = requests.post(url, headers=headers, json=params, timeout=30)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")
            
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise

    def search(
        self,
        term: str,
        search_on: Optional[str] = None,
        language: str = "English"
    ) -> Dict[str, Any]:
        """Search across Testbook's content.
        
        Args:
            term: Search query term (e.g., 'SSC', 'Banking', 'Railways')
            search_on: Comma-separated content types to search. 
                      Default: 'targets,courses,testSeries,tests,articles,quizzes'
            language: Language for results ('English' or 'Hindi'). Default: 'English'
            
        Returns:
            Dictionary with search results, counts, and ordering
        """
        params = {"term": term, "language": language}
        if search_on:
            params["search_on"] = search_on
        
        return self._call("search", method="GET", **params)

    def list_exam_categories(self, language: str = "English") -> Dict[str, Any]:
        """List all exam category super groups available on Testbook.
        
        Args:
            language: Language for results ('English' or 'Hindi'). Default: 'English'
            
        Returns:
            Dictionary containing list of exam categories
        """
        return self._call("list_exam_categories", method="GET", language=language)

    def get_upcoming_classes(
        self,
        super_group_id: Optional[str] = None,
        skip: int = 0,
        limit: int = 9,
        language: str = "English"
    ) -> Dict[str, Any]:
        """Get upcoming and live free classes for a given exam super group.
        
        Args:
            super_group_id: Super group ID from list_exam_categories. 
                           Default: Teaching Exams ID
            skip: Number of results to skip for pagination. Default: 0
            limit: Maximum number of lessons to return. Default: 9
            language: Language for results ('English' or 'Hindi'). Default: 'English'
            
        Returns:
            Dictionary containing lessons and count
        """
        params = {
            "skip": skip,
            "limit": limit,
            "language": language
        }
        if super_group_id:
            params["super_group_id"] = super_group_id
        
        return self._call("get_upcoming_classes", method="GET", **params)


def main():
    """Practical workflow demonstrating Testbook API usage."""
    
    # Initialize the client
    client = ParseClient()
    
    print("=" * 60)
    print("TESTBOOK EXAM PREPARATION API - PRACTICAL WORKFLOW")
    print("=" * 60)
    
    # Step 1: Get all exam categories
    print("\n[Step 1] Fetching all exam categories...")
    categories_response = client.list_exam_categories(language="English")
    categories = categories_response.get("categories", [])
    
    print(f"Found {len(categories)} exam categories:")
    for category in categories[:5]:  # Show first 5
        print(f"  • {category['title']}")
        print(f"    ID: {category['id']}")
        print(f"    Target Exams: {category['targets_count']}")
    
    # Step 2: Search for SSC exams
    print("\n[Step 2] Searching for 'SSC' exams...")
    search_results = client.search(
        term="SSC",
        search_on="targets,courses,testSeries",
        language="English"
    )
    
    # Extract and display search results
    if "count" in search_results:
        print("Search Results Summary:")
        for content_type, count_info in search_results["count"].items():
            value = count_info.get("value", 0)
            relation = count_info.get("relation", "eq")
            print(f"  • {content_type}: {value} ({relation})")
    
    # Display actual results per content type
    if "results" in search_results:
        results_data = search_results["results"]
        
        # Show targets (exams)
        if "targets" in results_data and results_data["targets"]:
            print(f"\nFound {len(results_data['targets'])} Target Exams:")
            for target in results_data["targets"][:3]:
                title = target.get("properties", {}).get("title", "Unknown")
                slug = target.get("slug", "")
                print(f"  • {title} (ID: {target.get('_id')})")
        
        # Show test series
        if "testSeries" in results_data and results_data["testSeries"]:
            print(f"\nFound {len(results_data['testSeries'])} Test Series:")
            for series in results_data["testSeries"][:3]:
                name = series.get("name", "Unknown")
                total_tests = series.get("paidTestCount", 0) + series.get("freeTestCount", 0)
                attempts = series.get("totalAttempts", 0)
                print(f"  • {name}")
                print(f"    Total Tests: {total_tests}, Attempts: {attempts:,}")
        
        # Show courses
        if "courses" in results_data and results_data["courses"]:
            print(f"\nFound {len(results_data['courses'])} Courses:")
            for course in results_data["courses"][:3]:
                name = course.get("name", "Unknown")
                print(f"  • {name}")
    
    # Step 3: Get upcoming classes for a specific category (Banking Exams)
    print("\n[Step 3] Fetching upcoming classes for Banking category...")
    
    # Find Banking Exams category
    banking_category = next(
        (cat for cat in categories if "Banking" in cat["title"]),
        None
    )
    
    if banking_category:
        classes_response = client.get_upcoming_classes(
            super_group_id=banking_category["id"],
            limit=5,
            language="English"
        )
        
        lessons = classes_response.get("lessons", [])
        print(f"Found {len(lessons)} upcoming/live classes for {banking_category['title']}:")
        
        for lesson in lessons[:3]:  # Show first 3
            name = lesson.get("name", "Unknown")
            start_time = lesson.get("start_time", "")
            series = lesson.get("series_name", "Unknown Series")
            instructors = lesson.get("instructors", [])
            is_live = lesson.get("is_live_now", False)
            
            print(f"\n  • {name}")
            print(f"    Series: {series}")
            if instructors:
                instructor_names = ", ".join([i.get("name", "Unknown") for i in instructors])
                print(f"    Instructor: {instructor_names}")
            
            if start_time:
                try:
                    scheduled_time = datetime.fromisoformat(start_time.replace('Z', '+00:00'))
                    print(f"    Scheduled: {scheduled_time.strftime('%Y-%m-%d %H:%M UTC')}")
                except (ValueError, AttributeError):
                    print(f"    Scheduled: {start_time}")
            
            if is_live:
                print("    Status: 🔴 LIVE NOW")
    
    # Step 4: Search for specific exam preparation content
    print("\n[Step 4] Searching for 'Railways' exam content...")
    railways_search = client.search(
        term="Railways",
        search_on="articles,tests,pyp",
        language="English"
    )
    
    if "count" in railways_search:
        print("Railways Content Available:")
        for content_type, count_info in railways_search["count"].items():
            value = count_info.get("value", 0)
            if value > 0:
                print(f"  • {content_type}: {value} items")
    
    print("\n" + "=" * 60)
    print("Workflow completed successfully!")
    print("=" * 60)


if __name__ == "__main__":
    main()