Ballotpedia APIballotpedia.org ↗

"""
Ballotpedia Courts and Judges API Client

Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for the Ballotpedia Courts and Judges 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 = "1345c3bd-ecb3-416f-9f80-50c8bbb64646"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Pass it as an argument or set PARSE_API_KEY environment variable."
            )

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

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

        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 list_states(self) -> Dict[str, Any]:
        """
        Get a list of all US states with court information available.

        Returns:
            Dictionary with 'states' (list of state names) and 'total' (count)
        """
        return self._call("list_states", method="GET")

    def list_courts(self, state: str) -> Dict[str, Any]:
        """
        Get a list of court types for a given state.

        Args:
            state: US state name (e.g., 'Alabama', 'California', 'New York')

        Returns:
            Dictionary with 'state', 'courts' (list of court names), and 'total'
        """
        return self._call("list_courts", method="GET", state=state)

    def list_justices(self, state: str, court_name: str) -> Dict[str, Any]:
        """
        Get a list of current justices/judges for a given court.

        Args:
            state: US state name
            court_name: Full court name as returned by list_courts

        Returns:
            Dictionary with 'state', 'court_name', 'justices' (list of justice objects), and 'total'
        """
        return self._call("list_justices", method="GET", state=state, court_name=court_name)


def main():
    """
    Practical usage example: Research supreme court justices across multiple states.
    """
    client = ParseClient()

    print("=" * 70)
    print("BALLOTPEDIA COURTS AND JUDGES API - RESEARCH WORKFLOW")
    print("=" * 70)

    # Step 1: Get all available states
    print("\n[1/4] Fetching available states...")
    states_response = client.list_states()
    available_states = states_response["states"]
    print(f"✓ Found {states_response['total']} states with court data")

    # Step 2: Select a few states to research (California, Texas, New York)
    states_to_research = ["California", "Texas", "New York"]
    states_to_research = [s for s in states_to_research if s in available_states]

    print(f"✓ Researching {len(states_to_research)} states: {', '.join(states_to_research)}")

    # Step 3: For each state, get courts and then get justices for supreme courts
    print("\n[2/4] Fetching courts for each state...")
    supreme_court_data = []

    for state in states_to_research:
        courts_response = client.list_courts(state)
        courts = courts_response["courts"]
        print(f"\n  {state}: {len(courts)} court types found")

        # Find the supreme court
        supreme_court = next((c for c in courts if "Supreme Court" in c), None)
        if supreme_court:
            print(f"    └─ Located: {supreme_court}")
            supreme_court_data.append((state, supreme_court))

    # Step 4: Fetch justices for each supreme court and analyze
    print("\n[3/4] Fetching justices for supreme courts...")
    all_justices = []

    for state, court_name in supreme_court_data:
        justices_response = client.list_justices(state, court_name)
        justices = justices_response["justices"]

        print(f"\n  {state} - {court_name}:")
        print(f"    Total justices: {len(justices)}")

        if justices:
            # Group by party
            party_counts = {}
            for justice in justices:
                party = justice.get("party", "Unknown")
                party_counts[party] = party_counts.get(party, 0) + 1
                all_justices.append(
                    {
                        "state": state,
                        "court": court_name,
                        "name": justice.get("name"),
                        "party": party,
                        "assumed_office": justice.get("date_assumed_office"),
                    }
                )

            # Display party breakdown
            for party, count in sorted(party_counts.items()):
                print(f"      • {party}: {count} justice(s)")

            # Show a sample of justices
            print("      Recent appointments:")
            recent = [j for j in justices if j.get("date_assumed_office")][:2]
            for justice in recent:
                print(
                    f"        - {justice.get('name')} ({justice.get('party')}) - {justice.get('date_assumed_office')}"
                )
        else:
            print("    ⚠ No individual justice data available for this court")

    # Step 5: Summary analysis
    print("\n[4/4] Summary Analysis")
    print("=" * 70)
    if all_justices:
        print(f"Total justices tracked: {len(all_justices)}")

        party_totals = {}
        for justice in all_justices:
            party = justice["party"]
            party_totals[party] = party_totals.get(party, 0) + 1

        print("\nParty Breakdown (All States):")
        for party, count in sorted(party_totals.items(), key=lambda x: x[1], reverse=True):
            percentage = (count / len(all_justices)) * 100
            print(f"  • {party}: {count} ({percentage:.1f}%)")

        # Show diversity across states
        print("\nJustices by State:")
        for state in states_to_research:
            state_justices = [j for j in all_justices if j["state"] == state]
            if state_justices:
                print(f"  • {state}: {len(state_justices)} justices")

    print("\n" + "=" * 70)
    print("✓ Research workflow completed successfully!")


if __name__ == "__main__":
    main()