CourtListener SDK (Unofficial)

Multi-language SDKs for the CourtListener API.

⚠️ Important Notice: This is an unofficial SDK developed by the community and is not affiliated with, endorsed by, or officially supported by CourtListener or Free Law Project.

Available Languages

Python SDK

• Location: python/
• Status: ✅ Complete and Production Ready
• Features: 100% API coverage, async/await support, comprehensive models, robust error handling
• Installation: pip install -r python/requirements.txt
• Async Support: ✅ AsyncClient with httpx for concurrent requests

PHP SDK

• Location: php/
• Status: ✅ Complete and Production Ready
• Features: 100% API coverage, promise-based async, comprehensive models, robust error handling
• Installation: composer install (in php/ directory)
• Async Support: ✅ AsyncClient with Guzzle promises for concurrent requests

Features

• 100% API Coverage: Complete support for all 39 CourtListener API endpoints
• Async/Concurrent Support: AsyncClient in Python (httpx) and promise-based async in PHP (Guzzle)
• Multi-Language Support: Python (complete) and PHP (complete)
• Comprehensive Data Models: Language-specific models for all data types including financial disclosures, alerts, people, and more
• Robust Error Handling: Production-ready error handling with retry logic and rate limiting
• Advanced Pagination: Cursor-based pagination support for efficient data retrieval
• Full CRUD Support: Create, read, update, and delete operations for alerts and docket alerts
• Comprehensive Test Coverage: 2,174+ tests across both languages with real API integration tests
• Easy Authentication: Simple authentication via .env file or direct token
• Extensive Documentation: Complete API reference and usage examples

Quick Start

Get started quickly with language-specific guides:

• Python: See Python Quick Start for detailed Python examples
• PHP: See PHP Quick Start for detailed PHP examples

Python

cd python
pip install -r requirements.txt

Synchronous:

from courtlistener import CourtListenerClient
client = CourtListenerClient()
dockets = client.dockets.list(page=1)
for docket in dockets:
    print(docket.case_name, docket.docket_number)

Async/Concurrent:

import asyncio
from courtlistener import AsyncCourtListenerClient

async def main():
    async with AsyncCourtListenerClient() as client:
        # Run multiple requests concurrently
        results = await asyncio.gather(
            client.courts.list(page=1),
            client.dockets.list(page=1),
            client.opinions.list(page=1),
        )
        return results

asyncio.run(main())

For more Python examples, see python/README.md.

PHP

cd php
composer install

Synchronous:

<?php
use CourtListener\CourtListenerClient;

$client = new CourtListenerClient();
$dockets = $client->dockets->list(['page' => 1]);
foreach ($dockets['results'] as $docket) {
    echo $docket['case_name'] . ' ' . $docket['docket_number'] . "\n";
}

Async/Promises:

<?php
use CourtListener\AsyncCourtListenerClient;
use GuzzleHttp\Promise\Utils;

$client = new AsyncCourtListenerClient();

// Run multiple requests concurrently
$promises = [
    'courts' => $client->getAsync('courts/', ['page' => 1]),
    'dockets' => $client->getAsync('dockets/', ['page' => 1]),
    'opinions' => $client->getAsync('opinions/', ['page' => 1]),
];

$results = Utils::unwrap($promises);

For more PHP examples, see php/README.md.

Development Tooling

Run these repo-root targets to keep both SDKs in sync:

Command	Purpose
make bootstrap	Install Python dev extras (pip install -e ".[dev]") and PHP Composer deps.
make lint	Run black, flake8, mypy, and phpstan in one go. Use python-lint/php-lint for individual SDKs.
make test	Execute pytest and composer test.
make build	Produce Python sdists/wheels (python -m build) and optimize Composer autoloaders.
make docs	Validate Markdown links across docs/ plus each language README via tools/check_docs.py.
make release	Sanity-check Python artifacts with twine check and package the PHP SDK as a zip via composer archive.
make clean	Remove virtualenv caches, build artifacts, and Composer vendor installs.

All targets accept the usual overrides (e.g., PYTHON=python3.12 make python-test). Use make help to list every available command.

Available Endpoints

Both Python and PHP SDKs provide access to all CourtListener API endpoints:

Core Endpoints

• client.courts — Court information and hierarchy
• client.dockets — Docket records and case information
• client.opinions — Judicial opinions and decisions
• client.clusters — Opinion clusters and related cases
• client.judges — Judicial biographical data
• client.positions — Judicial positions and appointments
• client.audio — Oral argument audio recordings
• client.search — Cross-resource search functionality

Financial & Disclosure Endpoints

• client.financial — Financial disclosure records
• client.financial_disclosures — Detailed financial disclosures
• client.investments — Investment holdings
• client.non_investment_incomes — Non-investment income sources
• client.gifts — Gift disclosures
• client.reimbursements — Reimbursement records
• client.debts — Debt disclosures
• client.spouse_incomes — Spouse income information
• client.agreements — Financial agreements

Case & Legal Endpoints

• client.docket_entries — Individual docket entries
• client.parties — Case participants and parties
• client.attorneys — Legal representation
• client.documents — RECAP document management
• client.recap_documents — RECAP document access
• client.citations — Citation graph and verification
• client.opinions_cited — Opinion citation relationships

People & Education Endpoints

• client.people — People and biographical data
• client.schools — Educational institutions
• client.educations — Educational background
• client.aba_ratings — ABA judicial ratings
• client.political_affiliations — Political affiliations

Alert & Notification Endpoints

• client.alerts — Search alerts and notifications
• client.docket_alerts — Docket-specific alerts

Administrative Endpoints

• client.sources — Data sources
• client.retention_events — Data retention events
• client.tag — Tagging system
• client.recap_fetch — RECAP fetch operations
• client.recap_query — RECAP query operations
• client.originating_court_information — Court origin data
• client.fjc_integrated_database — FJC database integration
• client.disclosure_positions — Disclosure position data

Authentication

Set your API token in a .env file:

COURTLISTENER_API_TOKEN=your_token_here

Python

client = CourtListenerClient(api_token="your_token_here")

PHP

$client = new CourtListenerClient(['api_token' => 'your_token_here']);

Tests & Debugging

Python

All manual and debug test scripts are in python/tests/manual_debug/. See the documentation for details on running and extending tests.

PHP

Comprehensive test suite with 2,174+ tests including unit, integration, mock, live, and E2E tests. Run with:

cd php
composer test

Documentation

Extensive documentation is available in docs/, including:

• User Guide
• API Reference
• Advanced Usage
• Troubleshooting

Language-Specific Documentation

• Python: See python/README.md for Python-specific details
• PHP: See php/README.md for PHP-specific details

Changelog

See CHANGELOG.md for release notes.

License

See LICENSE.

---

For more, see the full documentation.