Skip to main content

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-Remain and X-Ratelimit-Reset from 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-After or the reset time, then retries a bounded number of times before raising RateLimited;
  • retries 502, 503 and 504 with backoff, also bounded;
  • never sleeps longer than max_wait seconds (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)

Source distribution for companies-house 0.2.0
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)

Table of built distributions (wheels) for companies-house 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page