Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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-apiQuick 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: +SKIPError Handling
>>> import httpx # doctest: +SKIPAdvanced Usage
Sandbox Environment
>>> from ch_api import Client, api_settings # doctest: +SKIPCustom HTTP Session
>>> import httpx # doctest: +SKIPRequirements
- Python 3.11+
- httpx >= 0.28.1
- pydantic >= 2.12.5
Documentation
License
MIT License - See LICENSE file for details
Contributing
Please see CONTRIBUTING for development guidelines.