A modern Python SDK for accessing the UK Companies House API.
- Async-first: Built with modern async/await patterns for optimal performance
- Type-safe: Full type hints and Pydantic models for data validation
- Developer-friendly: Intuitive API with comprehensive documentation
- Lightweight: Minimal dependencies, fast installation
- Well-tested: Extensive test coverage with unit and integration tests
- Automatic Retry: Smart retry logic with exponential backoff for rate-limited requests
- Rate Limit Aware: Intelligent handling of API rate limits with configurable retry strategies
- Production Ready: Published on PyPI, thoroughly tested with live API
# Install from PyPI
pip install ukcompanies
# Or with uv
uv add ukcompaniesimport asyncio
from ukcompanies import AsyncClient
async def main():
# Initialize the client with your API key
async with AsyncClient(api_key="your-api-key") as client:
# Search for companies
results = await client.search_companies("OpenAI")
for company in results.items:
print(f"{company.title} - {company.company_number}")
# Get detailed company information
company = await client.profile("12345678")
print(f"Company: {company.company_name}")
print(f"Status: {company.company_status}")
asyncio.run(main())You'll need an API key from Companies House. Get one by:
- Registering at Companies House Developer Hub
- Creating an application
- Getting your API key
Create a .env file in your project root:
COMPANIES_HOUSE_API_KEY=your-api-key-hereThe SDK automatically handles rate limits with intelligent retry logic. You can customize retry behavior:
from ukcompanies import AsyncClient
# Custom retry configuration
async with AsyncClient(
api_key="your-api-key",
auto_retry=True, # Enable automatic retry (default: True)
max_retries=5, # Maximum retry attempts (default: 3)
backoff="exponential", # Backoff strategy: "exponential" or "fixed" (default: "exponential")
base_delay=1.0, # Base delay in seconds (default: 1.0)
max_delay=60.0, # Maximum delay between retries (default: 60.0)
jitter_range=1.0, # Random jitter range (default: 1.0)
on_retry=my_callback # Optional callback for retry events
) as client:
# Use client here
pass
# Custom retry callback
async def my_retry_callback(attempt, delay, response):
print(f"Retry attempt {attempt} after {delay}s delay")
async with AsyncClient(
api_key="your-api-key",
on_retry=my_retry_callback
) as client:
# Use client here
passThe SDK respects X-Ratelimit-Reset headers from the API for intelligent wait times and uses exponential backoff with jitter to prevent thundering herd problems.
This project uses uv for dependency management:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv pip install -e ".[dev]"# Run tests
pytest
# Run tests with coverage
pytest --cov=ukcompanies
# Run type checking
mypy src/ukcompanies
# Run linting
ruff check src/ tests/
# Format code
ruff format src/ tests/Documentation is built with MkDocs:
# Install documentation dependencies
uv pip install -e ".[docs]"
# Serve documentation locally
mkdocs serve
# Build documentation
mkdocs buildContributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.