Collegedunia APIcollegedunia.com ↗

"""
Collegedunia University Reviews API Client

Fetch and analyze student reviews for universities on Collegedunia.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Any, Dict
from urllib.parse import urljoin


class ParseClient:
    """Client for interacting with the Collegedunia University Reviews API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the ParseClient.

        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 = "7ca1b1a0-2fab-41be-8fc8-28b5b9650068"
        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 it as argument."
            )

    def _call(
        self, endpoint: str, method: str = "POST", **params
    ) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: API endpoint name
            method: HTTP method (GET or POST)
            **params: Query/body parameters

        Returns:
            Response data as dictionary

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

            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f"API request failed: {str(e)}")

    def get_university_reviews(
        self,
        university_slug: str,
        page: int = 1,
        stream_id: Optional[str] = None,
        degree_type: Optional[str] = None,
    ) -> Dict[str, Any]:
        """
        Get student reviews for a university on Collegedunia.

        Args:
            university_slug: University path slug (e.g., 'uk/university/865-university-of-oxford-oxford')
            page: Page number for paginated results (default: 1)
            stream_id: Filter by stream/subject ID (e.g., '339' for Computer Science)
            degree_type: Filter by degree type (e.g., 'Bachelor', 'Master')

        Returns:
            Dictionary containing reviews, stats, filters, and pagination info
        """
        params = {
            "university_slug": university_slug,
            "page": page,
        }

        if stream_id is not None:
            params["stream_id"] = stream_id

        if degree_type is not None:
            params["degree_type"] = degree_type

        return self._call("get_university_reviews", method="GET", **params)


def display_review(review: Dict[str, Any]) -> None:
    """Display a single review in a readable format."""
    print(f"\n{'='*70}")
    print(f"📝 {review.get('title', 'No title')}")
    print(f"👤 {review.get('name', 'Anonymous')}")
    print(f"📚 {review.get('course', 'N/A')}")
    print(f"📅 Enrollment: {review.get('enrollment', 'N/A')}")
    print(f"👍 {review.get('likes', 0)} likes | 👎 {review.get('dislikes', 0)} dislikes")

    if review.get("positive_points"):
        print("\n✅ Positive Points:")
        for point in review["positive_points"]:
            print(f"   • {point}")

    if review.get("negative_points"):
        print("\n❌ Negative Points:")
        for point in review["negative_points"]:
            print(f"   • {point}")


def display_review_stats(stats: Dict[str, Any]) -> None:
    """Display review statistics in a readable format."""
    print(f"\n{'='*70}")
    print("📊 REVIEW STATISTICS")
    print(f"{'='*70}")
    print(f"Total Reviews: {stats.get('total_reviews', 0)}")
    print(f"Average Rating: {stats.get('average_rating', 0):.2f}/10")

    rating = stats.get("rating", {})
    if rating:
        print("\nCategory Ratings:")
        print(f"  📚 Academic: {rating.get('avg_academic', 0):.2f}/10")
        print(f"  👨‍🏫 Faculty: {rating.get('avg_faculty', 0):.2f}/10")
        print(f"  🏗️  Infrastructure: {rating.get('avg_infrastructure', 0):.2f}/10")
        print(f"  🏠 Accommodation: {rating.get('avg_accomodation', 0):.2f}/10")
        print(f"  💼 Placement: {rating.get('avg_placement', 0):.2f}/10")
        print(f"  🎭 Extracurricular: {rating.get('avg_extracurricular', 0):.2f}/10")


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

    # Practical workflow: Fetch and analyze reviews for University of Oxford
    print("🎓 Collegedunia University Reviews Analysis")
    print("=" * 70)

    university_slug = "uk/university/865-university-of-oxford-oxford"
    print(f"\nFetching reviews for: {university_slug}")

    try:
        # Fetch first page of reviews
        response = client.get_university_reviews(university_slug, page=1)

        # Display university info
        print(f"\n✨ {response.get('university', 'University')}")
        total_reviews = response.get("total_reviews", 0)
        print(f"Total Reviews Available: {total_reviews}")

        # Display review statistics
        if "review_stats" in response:
            display_review_stats(response["review_stats"])

        # Display available filters
        filters = response.get("filters", {})
        if filters:
            print(f"\n🔍 Available Filters:")
            for filter_name, filter_data in filters.items():
                print(f"  • {filter_name}: {filter_data}")

        # Display pagination info
        pagination = response.get("pagination", {})
        current_page = pagination.get("current", 1)
        last_page = pagination.get("last", 1)
        print(f"\n📄 Pagination: Page {current_page} of {last_page}")

        # Display reviews from the first page
        reviews = response.get("reviews", [])
        print(f"\n📋 Displaying {len(reviews)} reviews from page {current_page}:")

        for idx, review in enumerate(reviews[:3], 1):  # Show first 3 reviews
            display_review(review)
            print()

        if len(reviews) > 3:
            print(f"\n... and {len(reviews) - 3} more reviews on this page")

        # Demonstrate multi-page fetching
        if last_page > 1:
            print(f"\n{'='*70}")
            print("📚 Fetching additional pages...")
            print(f"{'='*70}")

            for page_num in range(2, min(last_page + 1, 4)):  # Fetch up to 3 pages
                page_response = client.get_university_reviews(university_slug, page=page_num)
                page_reviews = page_response.get("reviews", [])
                print(f"\nPage {page_num}: Found {len(page_reviews)} reviews")

                if page_reviews:
                    first_review = page_reviews[0]
                    print(f"  Sample: {first_review.get('title', 'No title')} by {first_review.get('name', 'Anonymous')}")

        print(f"\n{'='*70}")
        print("✅ Analysis complete!")

    except Exception as e:
        print(f"❌ Error: {str(e)}")