Companies House API Python Client

Async Python client for the Companies House API with type-safe Pydantic models, automatic pagination, and comprehensive error handling.

Features

• Async-first with httpx
• Type-safe Pydantic models
• Automatic pagination handling
• Optional rate limiting
• 98%+ test coverage

Installation

pip install ch-api

Quick Start

Example of getting company information:

>>> async def get_company_example(client):
...     company = await client.get_company_profile("09370755")
...     return company is not None
>>> run_async_func(get_company_example)
True

Key Endpoints

• Company: get_company_profile(), get_officer_list(), get_company_psc_list(), get_company_charges(), get_company_filing_history()
• Search: search_companies(), search_officers(), search_disqualified_officers()
• Sandbox: create_test_company() (TEST_API_SETTINGS only)

Pagination

List endpoints return a MultipageList[T] with .data (tuple) and .pagination metadata. Pass result_count to collect more items per call, and advance with client.fetch_next_page(page.pagination.next_page):

>>> async def search_example(client):
...     results = await client.search_companies("tech")
...     return len(results.data) >= 1
>>> run_async_func(search_example)
True

pagination.next_page is a self-contained cursor — it embeds the endpoint and its arguments, so a fresh process can resume with just the token via await client.fetch_next_page(token) (ideal for stateless servers or agent tools).

Rate Limiting

The API allows 600 requests per 5 minutes. Use an async rate limiter:

>>> from asyncio_throttle import Throttler  # doctest: +SKIP

Error Handling

>>> import httpx  # doctest: +SKIP

Advanced Usage

Sandbox Environment

>>> from ch_api import Client, api_settings  # doctest: +SKIP

Custom HTTP Session

>>> import httpx  # doctest: +SKIP

Requirements

• Python 3.11+
• httpx >= 0.28.1
• pydantic >= 2.12.5

Documentation

• Full API Docs
• API Overview
• Usage Guide
• Contributing

License

MIT License - See LICENSE file for details

Contributing

Please see CONTRIBUTING for development guidelines.