IARDC APIiardc.org ↗

"""
IARDC Illinois Lawyer Search API - Parse Client

This module provides a Python client for searching and retrieving information about 
lawyers registered with the Illinois Attorney Registration & Disciplinary Commission.

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

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


class ParseClient:
    """Client for the IARDC Illinois Lawyer Search API."""
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API 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 = "920c0044-f2eb-4ad1-b3eb-26958f67469a"
        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 an API call to the Parse Bot scraper.
        
        Args:
            endpoint: The endpoint name (e.g., 'search_lawyers')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response data as dictionary
            
        Raises:
            requests.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.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()
        except requests.RequestException as e:
            raise requests.RequestException(f"API call failed: {e}")
    
    def search_lawyers(
        self,
        last_name: str = "",
        first_name: str = "",
        last_name_match: str = "Exact",
        status: str = "All",
        city: str = "",
        state: str = "",
        county: str = "",
        page: int = 1,
        page_size: int = 100
    ) -> Dict[str, Any]:
        """
        Search for lawyers in the IARDC database.
        
        Args:
            last_name: Last name to search for
            first_name: First name to search for
            last_name_match: Matching strategy ('Exact', 'BeginsWith', 'Contains')
            status: Registration status filter ('All', 'Active', 'Inactive')
            city: City to filter by
            state: State to filter by
            county: County to filter by
            page: Page number (1-based)
            page_size: Results per page (5, 10, 25, 50, 75, or 100)
            
        Returns:
            Dictionary containing lawyers list and pagination info
        """
        params = {
            "last_name": last_name,
            "first_name": first_name,
            "last_name_match": last_name_match,
            "status": status,
            "city": city,
            "state": state,
            "county": county,
            "page": page,
            "page_size": page_size
        }
        return self._call("search_lawyers", method="GET", **params)
    
    def get_lawyer_details(self, lawyer_id: str) -> Dict[str, Any]:
        """
        Get detailed profile information for a specific lawyer.
        
        Args:
            lawyer_id: The lawyer's IARDC GUID identifier (from search results)
            
        Returns:
            Dictionary containing detailed lawyer information
        """
        params = {"lawyer_id": lawyer_id}
        return self._call("get_lawyer_details", method="GET", **params)


def main():
    """Demonstrate practical usage of the IARDC Lawyer Search API."""
    
    # Initialize the client
    client = ParseClient()
    
    print("=" * 80)
    print("IARDC Illinois Lawyer Search - Practical Example")
    print("=" * 80)
    
    # Step 1: Search for active lawyers with last name "Smith" in Chicago
    print("\n[Step 1] Searching for active lawyers with last name 'Smith' in Chicago...")
    search_results = client.search_lawyers(
        last_name="Smith",
        last_name_match="Exact",
        city="Chicago",
        status="Active",
        page_size=10
    )
    
    if search_results.get('status') == 'success':
        data = search_results['data']
        print(f"✓ Found {data['result_count']} results on page {data['page']} "
              f"(Total pages: {data['total_pages']})")
    else:
        print("✗ Search failed")
        return
    
    # Step 2: Display search results summary
    if not data['lawyers']:
        print("No lawyers found matching the criteria.")
        return
    
    print("\n[Step 2] Search Results Summary:")
    print("-" * 80)
    for i, lawyer in enumerate(data['lawyers'], 1):
        print(f"{i}. {lawyer['name']}")
        print(f"   Location: {lawyer['city']}, {lawyer['state']}")
        print(f"   Admitted: {lawyer['date_admitted']}")
        print(f"   Practice Status: {lawyer['authorized_to_practice']}")
        print()
    
    # Step 3: Get detailed information for the first lawyer
    first_lawyer = data['lawyers'][0]
    lawyer_id = first_lawyer['id']
    lawyer_name = first_lawyer['name']
    
    print(f"[Step 3] Fetching detailed profile for: {lawyer_name}")
    print("-" * 80)
    
    details_response = client.get_lawyer_details(lawyer_id)
    
    if details_response.get('status') == 'success':
        details = details_response['data']
        print(f"Full Name: {details['full_name']}")
        print(f"Licensed Name: {details['full_licensed_name']}")
        print(f"Date Admitted: {details['date_admitted']}")
        print(f"Registration Status: {details['registration_status']}")
        print(f"Address: {details['registered_address']}")
        print(f"Phone: {details['registered_phone']}")
        print(f"Email: {details['registered_email']}")
        print(f"Malpractice Insurance: {details['malpractice_insurance']}")
        print(f"Discipline Record: {details['public_discipline_record']}")
    else:
        print("✗ Failed to fetch lawyer details")
    
    # Step 4: Search for multiple lawyers and get details for each
    print("\n" + "=" * 80)
    print("[Step 4] Searching for lawyers in Cook County and fetching their details...")
    print("-" * 80)
    
    cook_county_search = client.search_lawyers(
        county="Cook",
        status="Active",
        page_size=5
    )
    
    if cook_county_search.get('status') == 'success':
        cook_data = cook_county_search['data']
        print(f"Found {cook_data['result_count']} lawyers "
              f"(showing {len(cook_data['lawyers'])} on this page)\n")
        
        detailed_lawyers = []
        for i, lawyer in enumerate(cook_data['lawyers'][:3], 1):  # Get details for first 3
            print(f"Fetching details for: {lawyer['name']}...")
            detail = client.get_lawyer_details(lawyer['id'])
            
            if detail.get('status') == 'success':
                lawyer_detail = detail['data']
                detailed_lawyers.append({
                    'name': lawyer_detail['full_name'],
                    'status': lawyer_detail['registration_status'],
                    'address': lawyer_detail['registered_address'],
                    'phone': lawyer_detail['registered_phone']
                })
                print(f"  ✓ Retrieved details")
            else:
                print(f"  ✗ Failed to retrieve details")
        
        print("\n[Step 4] Summary of Detailed Profiles:")
        print("-" * 80)
        for lawyer in detailed_lawyers:
            print(f"Name: {lawyer['name']}")
            print(f"Status: {lawyer['status']}")
            print(f"Phone: {lawyer['phone']}")
            print()
    
    # Step 5: Search with different criteria (first name search)
    print("=" * 80)
    print("[Step 5] Searching for lawyers whose last name begins with 'Johnson'...")
    print("-" * 80)
    
    johnson_search = client.search_lawyers(
        last_name="Johnson",
        last_name_match="BeginsWith",
        status="Active",
        page_size=5
    )
    
    if johnson_search.get('status') == 'success':
        johnson_data = johnson_search['data']
        if johnson_data['lawyers']:
            print(f"Found {johnson_data['result_count']} results:\n")
            for lawyer in johnson_data['lawyers']:
                print(f"  • {lawyer['name']}")
                print(f"    {lawyer['city']}, {lawyer['state']} | "
                      f"Admitted: {lawyer['date_admitted']}")
        else:
            print("No lawyers found with that criteria.")
    
    print("\n" + "=" * 80)
    print("Example completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()