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, which is also free: how to get one, step by step, and what to check if it returns 401. 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.1

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.1
File Size Uploaded Provenance Actions
companies_house-0.2.1.tar.gz 24.1 kB With provenance Details for companies_house-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for companies-house 0.2.1
File Interpreter ABI Platform Actions
companies_house-0.2.1-py3-none-any.whl Python 3 none any Details for companies_house-0.2.1-py3-none-any.whl

Total release size: 35.7 kB

Release files / companies_house-0.2.1.tar.gz

Download URL companies_house-0.2.1.tar.gz
Size 24.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6f3a0e28572d2532904e26ebdf2f6efaf161fb9cf052f22214f31244248e1251
BLAKE2b-256 checksum
How to use checksums
631613eab250bb2c3f75ba275d9a6aa38dc1ef43d6ea324d9aa1f5ce0774ffc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 21, 2026.

Transparency log

Release files / companies_house-0.2.1-py3-none-any.whl

Download URL companies_house-0.2.1-py3-none-any.whl
Size 11.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
86e80f32ad18f95cfc6a3bbe708806ed16b9f66afc2b351ec3575b44ebb0ce66
BLAKE2b-256 checksum
How to use checksums
e8181458e116e382e3684a98567fbec72861d4568ba7f8725e008aa37c75e6a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 21, 2026.

Transparency log

Security for companies-house 0.2.1

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.1.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 21, 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.1 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