CUCAS APIcucas.cn ↗

"""
CUCAS (Study in China) 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 CUCAS scholarship and university search 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 env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "e76e626f-a956-47c4-9e35-8d0aa59ded21"
        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 a request to the Parse API.
        
        Args:
            endpoint: The endpoint name (e.g., 'search_scholarships')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response JSON as dictionary
        """
        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_scholarships(
        self,
        category: str = "all_scholarship",
        language: str = "all_languages",
        program: str = "all_programs",
        page: int = 1,
        degree: str = "all_degrees",
        city: str = "all_cities",
        university: str = "all_universities"
    ) -> Dict[str, Any]:
        """Search and filter available scholarships in China.
        
        Args:
            category: Scholarship category (all_scholarship, full, partial, etc.)
            language: Teaching language (English, Chinese, etc.)
            program: Program keyword or slug
            page: Page number
            degree: Academic degree (Bachelor, Master, Doctoral, etc.)
            city: City name or slug (e.g. beijing)
            university: University slug
            
        Returns:
            Dictionary with page, items, and total_results
        """
        params = {
            "category": category,
            "language": language,
            "program": program,
            "page": page,
            "degree": degree,
            "city": city,
            "university": university
        }
        return self._call("search_scholarships", method="GET", **params)

    def get_scholarship_detail(self, url: str) -> Dict[str, Any]:
        """Get detailed information about a specific scholarship.
        
        Args:
            url: Full URL of the scholarship detail page
            
        Returns:
            Dictionary with scholarship details including eligibility, deadlines, etc.
        """
        params = {"url": url}
        return self._call("get_scholarship_detail", method="GET", **params)

    def list_popular_scholarships(self) -> Dict[str, Any]:
        """List popular scholarships as featured on CUCAS.
        
        Returns:
            Dictionary with items array of scholarship objects
        """
        return self._call("list_popular_scholarships", method="GET")

    def list_latest_scholarships(self) -> Dict[str, Any]:
        """List latest scholarships added to CUCAS.
        
        Returns:
            Dictionary with items array of scholarship objects
        """
        return self._call("list_latest_scholarships", method="GET")

    def list_universities(self, letter: str = "A", page: int = 1) -> Dict[str, Any]:
        """List Chinese universities with filtering by alphabetical letter.
        
        Args:
            letter: Alphabetical letter (A-Z)
            page: Page number
            
        Returns:
            Dictionary with items array of university objects
        """
        params = {"letter": letter, "page": page}
        return self._call("list_universities", method="GET", **params)

    def search_programs(self, query: str) -> Dict[str, Any]:
        """Search for academic programs across universities.
        
        Args:
            query: Search keyword (e.g. Computer Science)
            
        Returns:
            Dictionary with results array containing universities and their matching programs
        """
        params = {"query": query}
        return self._call("search_programs", method="GET", **params)


def main():
    """Demonstrate practical usage of the CUCAS API."""
    
    # Initialize the client
    client = ParseClient()
    
    print("=" * 80)
    print("CUCAS Scholarship Search - Practical Workflow")
    print("=" * 80)
    
    # Step 1: Search for scholarships in Beijing for Master's degree
    print("\n1. Searching for Master's scholarships in Beijing...")
    search_results = client.search_scholarships(
        city="beijing",
        degree="Master",
        category="full",
        page=1
    )
    
    total_results = search_results.get("total_results", 0)
    items = search_results.get("items", [])
    
    print(f"   Found {total_results} total scholarships")
    print(f"   Displaying {len(items)} results on this page")
    
    if items:
        # Step 2: Show summary of first few scholarships
        print("\n2. Available scholarships summary:")
        for i, scholarship in enumerate(items[:3], 1):
            print(f"\n   Scholarship {i}:")
            print(f"   - University: {scholarship.get('university', 'N/A')}")
            print(f"   - Program: {scholarship.get('program_name', 'N/A')}")
            print(f"   - Location: {scholarship.get('location', 'N/A')}")
            print(f"   - Language: {scholarship.get('teaching_language', 'N/A')}")
            print(f"   - Coverage: {scholarship.get('scholarship_coverage', 'N/A')[:50]}...")
            print(f"   - Rating: {scholarship.get('university_rating', 'N/A')}")
            print(f"   - Detail URL: {scholarship.get('detail_url', 'N/A')[:60]}...")
        
        # Step 3: Get detailed information for the first scholarship
        if items[0].get('detail_url'):
            print("\n3. Fetching detailed information for first scholarship...")
            detail_url = items[0]['detail_url']
            
            detail_info = client.get_scholarship_detail(detail_url)
            
            print(f"\n   University: {detail_info.get('university', 'N/A')}")
            print(f"   Program: {detail_info.get('program_title', 'N/A')}")
            print(f"   Status: {'Available' if detail_info.get('is_still_available') else 'Not Available'}")
            
            if detail_info.get('program_info'):
                print(f"   Program Info:")
                for key, value in detail_info['program_info'].items():
                    print(f"     - {key}: {value}")
            
            if detail_info.get('deadlines'):
                print(f"   Important Deadlines:")
                for key, value in detail_info['deadlines'].items():
                    print(f"     - {key}: {value}")
            
            if detail_info.get('eligibility'):
                print(f"   Eligibility: {detail_info['eligibility'][:100]}...")
            
            if detail_info.get('scholarship_coverage_details'):
                print(f"   Coverage: {detail_info['scholarship_coverage_details'][:100]}...")
            
            if detail_info.get('documents_required'):
                print(f"   Required Documents: {detail_info['documents_required'][:100]}...")
    
    # Step 4: Search for programs
    print("\n4. Searching for Computer Science programs...")
    program_search = client.search_programs("Computer Science")
    
    results = program_search.get("results", [])
    print(f"   Found {len(results)} universities with Computer Science programs")
    
    for university_result in results[:3]:
        uni_name = university_result.get('university', 'N/A')
        programs = university_result.get('programs', [])
        print(f"   - {uni_name}: {len(programs)} program(s)")
        for program in programs[:2]:
            print(f"     * {program.get('name', 'N/A')}")
    
    # Step 5: List popular scholarships
    print("\n5. Fetching popular scholarships...")
    popular = client.list_popular_scholarships()
    popular_items = popular.get("items", [])
    print(f"   Found {len(popular_items)} popular scholarships")
    
    for scholarship in popular_items[:3]:
        print(f"   - {scholarship.get('university', 'N/A')}")
    
    # Step 6: List universities by letter
    print("\n6. Listing universities starting with 'T'...")
    universities = client.list_universities(letter="T", page=1)
    uni_items = universities.get("items", [])
    print(f"   Found {len(uni_items)} universities starting with 'T'")
    
    for university in uni_items[:3]:
        print(f"   - {university.get('name', 'N/A')}")
        print(f"     Location: {university.get('location', 'N/A')}")
        print(f"     Rating: {university.get('rating', 'N/A')}")
        print(f"     Living Expenses: {university.get('living_expenses', 'N/A')}")
    
    print("\n" + "=" * 80)
    print("Workflow completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()