Async Python client for the Companies House API with type-safe Pydantic models, automatic pagination, and comprehensive error handling.
- Async-first with
httpx - Type-safe Pydantic models
- Automatic pagination handling
- Optional rate limiting
- 98%+ test coverage
pip install ch-apiExample 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
- 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)
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).
The API allows 600 requests per 5 minutes. Use an async rate limiter:
>>> from asyncio_throttle import Throttler # doctest: +SKIP>>> import httpx # doctest: +SKIP>>> from ch_api import Client, api_settings # doctest: +SKIP>>> import httpx # doctest: +SKIP- Python 3.11+
- httpx >= 0.28.1
- pydantic >= 2.12.5
MIT License - See LICENSE file for details
Please see CONTRIBUTING for development guidelines.