JSTOR APIjstor.org ↗

"""
JSTOR Content API Client

Search and browse academic content on JSTOR, including articles, journals, and issues.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for the JSTOR Content API via Parse.bot"""

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

        Args:
            api_key: API key for Parse.bot. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "b54cfcb7-298c-4413-9f6b-8f47f56ef1d1"
        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', 'get_article')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters for the endpoint

        Returns:
            Response JSON as a dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        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()

    def search(
        self, query: str, sort: str = "rel", page: int = 1
    ) -> Dict[str, Any]:
        """
        Search for articles, books, and other content on JSTOR.

        Args:
            query: Search query string
            sort: Sort order ('rel' for relevance, 'new' for newest, 'old' for oldest)
            page: Page number for pagination

        Returns:
            Search results with total count and article metadata
        """
        return self._call("search", method="GET", query=query, sort=sort, page=page)

    def get_article(self, article_id: str) -> Dict[str, Any]:
        """
        Retrieve full metadata for a specific article or book chapter by its JSTOR UUID.

        Args:
            article_id: The JSTOR UUID of the article

        Returns:
            Full article metadata including abstract, authors, and publication details
        """
        return self._call("get_article", method="GET", article_id=article_id)

    def get_issue(self, issue_id: str) -> Dict[str, Any]:
        """
        Retrieve the table of contents for a specific journal issue.

        Args:
            issue_id: The DOI-style stable ID of the issue

        Returns:
            Issue metadata and list of articles in the issue
        """
        return self._call("get_issue", method="GET", issue_id=issue_id)

    def get_journal(self, journal_id: str) -> Dict[str, Any]:
        """
        Retrieve metadata for a specific journal by its ID slug.

        Args:
            journal_id: The journal ID slug (e.g., 'aejapplecon')

        Returns:
            Journal metadata including title, publisher, ISSN, and description
        """
        return self._call("get_journal", method="GET", journal_id=journal_id)

    def browse_subjects(self) -> Dict[str, Any]:
        """
        List all browseable academic subjects on JSTOR.

        Returns:
            List of subjects with codes, names, and URLs
        """
        return self._call("browse_subjects", method="GET")


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

    print("=" * 80)
    print("JSTOR Content API - Academic Research Discovery Workflow")
    print("=" * 80)

    # Step 1: Browse available research subjects
    print("\n[1] Discovering Research Subjects...")
    print("-" * 80)
    
    subjects_response = client.browse_subjects()
    subjects = subjects_response.get("data", [])
    
    print(f"Available subjects: {len(subjects)}")
    for subject in subjects[:5]:
        print(f"  • {subject['name']} ({subject['code']})")
    if len(subjects) > 5:
        print(f"  ... and {len(subjects) - 5} more")

    # Step 2: Search for recent articles on climate change
    print("\n[2] Searching for Recent Climate Change Research...")
    print("-" * 80)
    
    search_results = client.search(query="climate change", sort="new", page=1)
    
    print(f"Search Query: '{search_results['query']}'")
    print(f"Total Results Available: {search_results['total_results']}")
    print(f"Results on Current Page: {len(search_results['results'])}")
    
    # Step 3: Analyze and fetch details for top results
    print("\n[3] Analyzing Top Research Articles...")
    print("-" * 80)
    
    results_to_analyze = search_results["results"][:3]
    article_details_list = []
    
    for idx, article in enumerate(results_to_analyze, 1):
        print(f"\nArticle {idx}: {article['title'][:70]}")
        print(f"  Authors: {', '.join(article['authors'][:2])}")
        print(f"  Type: {article['type']} | Year: {article['publication_year']}")
        print(f"  Open Access: {article['is_open_access']} | Access Available: {article['has_access']}")
        print(f"  DOI: {article.get('doi', 'N/A')[:40]}")
        
        # Fetch full article details
        try:
            article_detail = client.get_article(article['id'])
            article_details_list.append(article_detail)
            
            print(f"  Publisher: {article_detail.get('publisher', 'N/A')}")
            if article_detail.get('abstract'):
                abstract_preview = article_detail['abstract'][:100]
                print(f"  Abstract Preview: {abstract_preview}...")
            print(f"  Permanent URL: {article_detail['stable_url']}")
            
        except Exception as e:
            print(f"  ⚠ Could not fetch full details: {str(e)[:50]}")

    # Step 4: Aggregate findings
    print("\n[4] Research Summary...")
    print("-" * 80)
    
    print(f"\nSuccessfully retrieved {len(article_details_list)} detailed articles")
    
    if article_details_list:
        # Analyze publication years
        years = [int(a.get('year', 0)) for a in article_details_list if a.get('year')]
        if years:
            avg_year = sum(years) / len(years)
            print(f"Average Publication Year: {avg_year:.1f}")
            print(f"Year Range: {min(years)} - {max(years)}")
        
        # Analyze authors
        all_authors = []
        for article in article_details_list:
            all_authors.extend(article.get('authors', []))
        
        print(f"Total Authors Across Results: {len(all_authors)}")
        if all_authors:
            print(f"Prolific Authors: {', '.join(set(all_authors[:3]))}")
        
        # Content types
        content_types = set(a.get('type', 'Unknown') for a in article_details_list)
        print(f"Content Types Found: {', '.join(content_types)}")

    print("\n" + "=" * 80)
    print("Research discovery workflow complete!")
    print("=" * 80)