Hillsclerk APIpublicaccess.hillsclerk.com ↗

"""
Hillsborough County Clerk of Court API - Parse Client

Access court records, foreclosure judgments, and case details from the
Hillsborough County Clerk of Court (HOVER) portal.

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

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


class ParseClient:
    """Client for interacting with the Hillsborough County Clerk of Court 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 environment variable.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "0f4a0650-c0ce-4ead-9fc5-30b7c33b86dd"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not found. Set PARSE_API_KEY environment variable "
                "or pass it to ParseClient(api_key='...')"
            )

    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 to send

        Returns:
            Response JSON as dictionary

        Raises:
            requests.RequestException: If the request fails
        """
        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:
            response = requests.post(url, headers=headers, json=params)

        response.raise_for_status()
        return response.json()

    def search_foreclosure_judgment_records(
        self, date: str = "07/28/2025"
    ) -> Dict[str, Any]:
        """
        Search for foreclosure-related cases filed on a specific date.

        Filters results for 'FORECLOSURE' or 'MORTGAGE' in the case type description.

        Args:
            date: Date filed in MM/DD/YYYY format. Defaults to 07/28/2025.

        Returns:
            Dictionary containing total_found count, date, and cases array
        """
        return self._call("search_foreclosure_judgment_records", method="GET", date=date)

    def get_foreclosure_judgment_details(self, case_number: str) -> Dict[str, Any]:
        """
        Retrieve comprehensive details for a specific foreclosure case.

        Includes parties, judgments, and docket events.

        Args:
            case_number: Case number (e.g., 25-CA-001234)

        Returns:
            Dictionary containing summary, judgments, events, and parties
        """
        return self._call(
            "get_foreclosure_judgment_details", method="GET", case_number=case_number
        )

    def search_by_date_range_court_type(
        self,
        date_after: str,
        date_before: str,
        court_type: str = "CV",
        case_status: str = "A",
        case_type: str = "ALL",
    ) -> Dict[str, Any]:
        """
        General search for court cases by date range, court type, and case status.

        Args:
            date_after: Date filed on or after (MM/DD/YYYY)
            date_before: Date filed on or before (MM/DD/YYYY)
            court_type: Court category (CV=Civil, CR=Criminal, etc.). Defaults to 'CV'.
            case_status: Case status (A=All, O=Open, C=Closed). Defaults to 'A'.
            case_type: Case type (e.g., CV for Civil). Defaults to 'ALL'.

        Returns:
            Dictionary containing recordsTotal, recordsFiltered, and data array
        """
        return self._call(
            "search_by_date_range_court_type",
            method="GET",
            date_after=date_after,
            date_before=date_before,
            court_type=court_type,
            case_status=case_status,
            case_type=case_type,
        )

    def search_by_case_number(self, case_number: str) -> Dict[str, Any]:
        """
        Search for a specific case by its case number.

        Args:
            case_number: Full case number (e.g., 25-CC-032147)

        Returns:
            Dictionary containing data array with matching case
        """
        return self._call("search_by_case_number", method="GET", case_number=case_number)


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

    print("=" * 70)
    print("Hillsborough County Clerk of Court - Case Research Workflow")
    print("=" * 70)

    # Step 1: Search for recent foreclosure cases
    print("\n[1] Searching for foreclosure cases filed on 07/28/2025...")
    foreclosure_results = client.search_foreclosure_judgment_records(date="07/28/2025")

    print(f"   Found {foreclosure_results['total_found']} foreclosure case(s)")

    if foreclosure_results["cases"]:
        # Step 2: Process each foreclosure case
        for idx, case in enumerate(foreclosure_results["cases"], 1):
            case_num = case["caseNumber"]
            filed_date = case["caseFiledOn"]
            case_type = case["caseTypeDescription"]

            print(f"\n[2.{idx}] Retrieving details for case: {case_num}")
            print(f"      Type: {case_type}")
            print(f"      Filed: {filed_date}")

            # Step 3: Get detailed information for this case
            try:
                details = client.get_foreclosure_judgment_details(case_number=case_num)

                # Display case summary
                summary = details.get("summary", {})
                print(f"      Status: {summary.get('caseStatus', 'Unknown')}")

                # Display parties involved
                parties = details.get("parties", [])
                if parties:
                    print(f"      Parties ({len(parties)}):")
                    for party in parties:
                        print(
                            f"        - {party.get('partyName', 'Unknown')} "
                            f"({party.get('partyRoleDescription', 'Unknown')})"
                        )

                # Display judgments
                judgments = details.get("judgments", [])
                if judgments:
                    print(f"      Judgments ({len(judgments)}):")
                    for judgment in judgments:
                        jtype = judgment.get("judgmentType", "Unknown")
                        jdate = judgment.get("judgmentDate", "Unknown")
                        jamount = judgment.get("judgmentAmount", "N/A")
                        print(f"        - {jtype} ({jdate}): ${jamount:,}")

                # Display recent docket events
                events = details.get("events", [])
                if events:
                    print(f"      Recent Events ({len(events)}):")
                    for event in events[:3]:
                        event_date = event.get("filedDate", "Unknown")
                        event_desc = event.get("eventDescription", "Unknown")
                        print(f"        - [{event_date}] {event_desc}")
                    if len(events) > 3:
                        print(f"        ... and {len(events) - 3} more events")

            except requests.RequestException as e:
                print(f"      Error retrieving details: {e}")

    # Step 4: Search for civil cases in a date range
    print("\n[3] Searching for civil cases filed in the last 7 days...")
    today = datetime.now()
    week_ago = today - timedelta(days=7)

    date_after = week_ago.strftime("%m/%d/%Y")
    date_before = today.strftime("%m/%d/%Y")

    try:
        civil_results = client.search_by_date_range_court_type(
            date_after=date_after, date_before=date_before, court_type="CV"
        )

        records_total = civil_results.get("recordsTotal", 0)
        records_filtered = civil_results.get("recordsFiltered", 0)

        print(f"   Found {records_filtered} civil case(s) from {date_after} to {date_before}")

        # Display first 5 cases
        cases = civil_results.get("data", [])
        for idx, case in enumerate(cases[:5], 1):
            case_num = case.get("caseNumber", "Unknown")
            case_status = case.get("caseStatus", "Unknown")
            case_type = case.get("caseTypeDescription", "Unknown")
            print(f"      {idx}. {case_num} - {case_type} ({case_status})")

        if len(cases) > 5:
            print(f"      ... and {len(cases) - 5} more cases")

    except requests.RequestException as e:
        print(f"   Error searching civil cases: {e}")

    print("\n" + "=" * 70)
    print("Search completed successfully!")
    print("=" * 70)