companies-house
A Python client for the Companies House API that stays inside the rate limit instead of finding it by getting banned.
from companies_house import CompaniesHouse
ch = CompaniesHouse("your-ch-api-key") # pip install companies-house
print(ch.company("445790")["company_name"]) # TESCO PLC
Free to use with your own Companies House API key. One dependency (httpx), Python 3.9+, typed, returns plain dicts.
What it covers
ch.search("tesco") # one page of search results
ch.officers("445790") # directors and secretaries
ch.psc("445790") # persons with significant control
ch.filing_history("445790", category="accounts")
ch.charges("445790")
for company in ch.iter_search("tesco", limit=250): # pages for you
...
for filing in ch.iter_filing_history("445790"):
...
Company numbers are normalised for you: 445790 becomes 00445790, sc123456 becomes SC123456.
Rate limits
Companies House allows a fixed number of requests per key in a five minute window (documented as 600) and bans keys that keep going after they are told to stop. This client:
- reads
X-Ratelimit-RemainandX-Ratelimit-Resetfrom every response and sleeps until the window resets when you are nearly out, so it does not trigger the 429 in the first place; - on a 429, waits for
Retry-Afteror the reset time, then retries a bounded number of times before raisingRateLimited; - retries 502, 503 and 504 with backoff, also bounded;
- never sleeps longer than
max_waitseconds (310 by default); past that it raises instead of hanging.
from companies_house import CompaniesHouse, NotFound, RateLimited, AuthError
ch = CompaniesHouse(key, max_retries=3, low_watermark=5, max_wait=310)
try:
ch.company("00000000")
except NotFound:
...
except RateLimited as e:
print("try again in", e.retry_after, "seconds")
except AuthError as e:
print(e) # explains Basic auth, key type, live vs sandbox
print(ch.rate_limit.remaining, "of", ch.rate_limit.limit, "left")
The clock and sleep are injectable (clock=, sleep=), so you can test your own code against it.
Need financials or ownership chains?
The official API returns filing metadata, not figures, and gives you one PSC level at a time. Registrum is a hosted API over the same data that adds structured financials from filed accounts and the full ownership chain to the people at the top. The client has the same shape:
from companies_house import Registrum
reg = Registrum("your-registrum-key") # or set REGISTRUM_API_KEY
reg.financials("445790") # figures from filed accounts, where available
reg.psc_chain("445790") # follows corporate owners upwards
reg.bundle("445790", include=["profile", "financials", "psc"])
No key yet? Ask for a trial with an email address:
reg = Registrum()
reg.start_trial("you@example.com") # we email a confirmation link
The key does not work until you click that link; until then calls raise TrialUnverified with the reason. Limits and plans are on the pricing page.
Notes
- Synchronous only for now.
- Sends
User-Agent: companies-house-python/<version>so the services you call can see which client is talking to them. - Not affiliated with Companies House. Contains public sector information licensed under the Open Government Licence v3.0.
Issues and pull requests are welcome. Security reports: see SECURITY.md. MIT licence.
Metadata
Release files for companies-house 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| companies_house-0.2.0.tar.gz | 24.0 kB | With provenance | Details for companies_house-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| companies_house-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for companies_house-0.2.0-py3-none-any.whl |
Total release size: 35.6 kB
Release files / companies_house-0.2.0.tar.gz
| Download URL | companies_house-0.2.0.tar.gz |
|---|---|
| Size | 24.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3b42d40ffcae6b7a068016a6c4d7b095d21faa5e61926da18b7acc61d3417376
|
|
BLAKE2b-256 checksum How to use checksums |
f8902b9746725ae25321fd87e2e38e8688b8ef360cd3835350b7080d07e750ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / companies_house-0.2.0-py3-none-any.whl
| Download URL | companies_house-0.2.0-py3-none-any.whl |
|---|---|
| Size | 11.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e120867c6bc7601dade0f2ad9712201c72a5d9e1d7e43c59ec1bebc6d9d96345
|
|
BLAKE2b-256 checksum How to use checksums |
30f072dda01157231d4487242919c78be66d7bc9fbb0048a5955253a2588e46b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logSecurity for companies-house 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for companies_house-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.