Multi-language SDKs for the CourtListener API.
- 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
- Location:
php/ - Status: ✅ Complete and Production Ready
- Features: 100% API coverage, promise-based async, comprehensive models, robust error handling
- Installation:
composer install(inphp/directory) - Async Support: ✅ AsyncClient with Guzzle promises for concurrent requests
- 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
.envfile or direct token - Extensive Documentation: Complete API reference and usage examples
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
cd python
pip install -r requirements.txtSynchronous:
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.
cd php
composer installSynchronous:
<?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.
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.
Both Python and PHP SDKs provide access to all CourtListener API endpoints:
client.courts— Court information and hierarchyclient.dockets— Docket records and case informationclient.opinions— Judicial opinions and decisionsclient.clusters— Opinion clusters and related casesclient.judges— Judicial biographical dataclient.positions— Judicial positions and appointmentsclient.audio— Oral argument audio recordingsclient.search— Cross-resource search functionality
client.financial— Financial disclosure recordsclient.financial_disclosures— Detailed financial disclosuresclient.investments— Investment holdingsclient.non_investment_incomes— Non-investment income sourcesclient.gifts— Gift disclosuresclient.reimbursements— Reimbursement recordsclient.debts— Debt disclosuresclient.spouse_incomes— Spouse income informationclient.agreements— Financial agreements
client.docket_entries— Individual docket entriesclient.parties— Case participants and partiesclient.attorneys— Legal representationclient.documents— RECAP document managementclient.recap_documents— RECAP document accessclient.citations— Citation graph and verificationclient.opinions_cited— Opinion citation relationships
client.people— People and biographical dataclient.schools— Educational institutionsclient.educations— Educational backgroundclient.aba_ratings— ABA judicial ratingsclient.political_affiliations— Political affiliations
client.alerts— Search alerts and notificationsclient.docket_alerts— Docket-specific alerts
client.sources— Data sourcesclient.retention_events— Data retention eventsclient.tag— Tagging systemclient.recap_fetch— RECAP fetch operationsclient.recap_query— RECAP query operationsclient.originating_court_information— Court origin dataclient.fjc_integrated_database— FJC database integrationclient.disclosure_positions— Disclosure position data
Set your API token in a .env file:
COURTLISTENER_API_TOKEN=your_token_here
client = CourtListenerClient(api_token="your_token_here")$client = new CourtListenerClient(['api_token' => 'your_token_here']);All manual and debug test scripts are in python/tests/manual_debug/. See the documentation for details on running and extending tests.
Comprehensive test suite with 2,174+ tests including unit, integration, mock, live, and E2E tests. Run with:
cd php
composer testExtensive documentation is available in docs/, including:
- Python: See
python/README.mdfor Python-specific details - PHP: See
php/README.mdfor PHP-specific details
See CHANGELOG.md for release notes.
See LICENSE.
For more, see the full documentation.