journalranking APIjournalranking.org ↗

"""
ABS Journal Ranking Database API Client

Access the complete ABS (Academic Journal Guide) Journal Ranking 2024 database
with 1,635 journal entries. Search and filter by keyword, field, and ranking level.

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 ABS Journal Ranking Database 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 = "4dea2416-56ea-4e00-8c00-7292b9245234"
        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 API.

        Args:
            endpoint: The endpoint name (e.g., 'get_all_entries')
            method: HTTP method ('GET' or 'POST')
            **params: Query/payload 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 == "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:
            print(f"API Error: {e}")
            raise

    def get_all_entries(self) -> Dict[str, Any]:
        """
        Retrieve all 1,635 entries in the ABS Journal Ranking 2024 database.

        Each entry includes ISSN, field of study, journal title, publisher,
        and AJG rankings for 2024, 2021, and 2018.

        Returns:
            Dictionary containing total count and list of journal entries
        """
        return self._call("get_all_entries", method="GET")

    def search_entries(
        self,
        query: Optional[str] = None,
        field: Optional[str] = None,
        ranking: Optional[str] = None,
        page: int = 1,
        limit: int = 50,
    ) -> Dict[str, Any]:
        """
        Search and filter ABS Journal Ranking entries.

        Args:
            query: Search keyword to match against journal title, publisher, or ISSN
            field: Filter by field of study (e.g., 'ACCOUNT', 'FINANCE', 'MKT')
            ranking: Filter by AJG 2024 ranking level ('1', '2', '3', '4', '4*')
            page: Page number for pagination (1-based, default: 1)
            limit: Number of results per page, 1-1000 (default: 50)

        Returns:
            Dictionary containing total count, page info, and paginated entries
        """
        params = {
            "page": page,
            "limit": limit,
        }

        if query is not None:
            params["query"] = query
        if field is not None:
            params["field"] = field
        if ranking is not None:
            params["ranking"] = ranking

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


def print_journal_entry(entry: Dict[str, str]) -> None:
    """Pretty print a single journal entry."""
    print(f"  Title: {entry['title']}")
    print(f"  ISSN: {entry['issn']}")
    print(f"  Field: {entry['field']}")
    print(f"  Publisher: {entry['publisher']}")
    print(f"  AJG 2024: {entry['ajg2024']} | 2021: {entry['ajg2021']} | 2018: {entry['ajg2018']}")
    print()


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

    print("=" * 80)
    print("ABS Journal Ranking Database - Practical Usage Example")
    print("=" * 80)
    print()

    # Use Case 1: Find top-tier accounting journals
    print("📊 Use Case 1: Finding Top-Tier Accounting Journals (Rank 4*)")
    print("-" * 80)
    accounting_results = client.search_entries(
        field="ACCOUNT",
        ranking="4*",
        limit=10,
    )

    print(f"Found {accounting_results['total']} 4* ranked accounting journals")
    print(f"Showing page {accounting_results['page']} ({len(accounting_results['entries'])} results)\n")

    for entry in accounting_results["entries"]:
        print_journal_entry(entry)

    # Use Case 2: Search for specific journals by keyword
    print("🔍 Use Case 2: Searching for 'Management' Journals")
    print("-" * 80)
    management_results = client.search_entries(
        query="Management",
        limit=5,
    )

    print(f"Found {management_results['total']} journals matching 'Management'\n")

    # Collect rankings distribution across pages
    ranking_distribution = {}
    for entry in management_results["entries"]:
        ranking = entry["ajg2024"]
        ranking_distribution[ranking] = ranking_distribution.get(ranking, 0) + 1
        print_journal_entry(entry)

    print(f"Ranking distribution for 'Management' journals on this page:")
    for ranking, count in sorted(ranking_distribution.items()):
        print(f"  {ranking}: {count} journal(s)")
    print()

    # Use Case 3: Analyze journals in specific field (Finance)
    print("💰 Use Case 3: Finance Field Analysis")
    print("-" * 80)
    finance_results = client.search_entries(
        field="FINANCE",
        limit=15,
    )

    print(f"Total finance journals in database: {finance_results['total']}\n")

    # Analyze rankings
    rankings_count = {}
    for entry in finance_results["entries"]:
        ranking = entry["ajg2024"]
        rankings_count[ranking] = rankings_count.get(ranking, 0) + 1

    print("Top Finance Journals (from current page):")
    for entry in finance_results["entries"]:
        if entry["ajg2024"] in ["4*", "4"]:
            print(f"  • {entry['title']} ({entry['ajg2024']})")
    print()

    # Use Case 4: Compare journals across different ranking levels
    print("📈 Use Case 4: Comparing Journals Across Ranking Levels")
    print("-" * 80)

    ranking_levels = ["4*", "4", "3", "2", "1"]
    samples_per_level = {}

    for level in ranking_levels:
        result = client.search_entries(ranking=level, limit=3)
        samples_per_level[level] = result["entries"]
        print(f"\nRanking Level {level} (showing 3 of {result['total']} total):")
        for entry in result["entries"]:
            print(f"  • {entry['title'][:50]}... by {entry['publisher']}")

    print()
    print("=" * 80)
    print("✅ Usage examples completed successfully!")
    print("=" * 80)