---
name: companies-house-api-ingestion
description: "How to get UK Companies House Public Data API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Search Companies House data into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/companies-house-api
Provider: https://developer.company-information.service.gov.uk/
Checked against the provider's documentation: 2026-11-02

## Access
- Create a Companies House account, application and API key.
- Set COMPANIES_HOUSE_API_KEY in the environment; public GET requests use the key as the Basic Auth username with an empty password.

## Request
```bash
curl --user "$COMPANIES_HOUSE_API_KEY:" --get --data-urlencode 'q=energy' --data-urlencode 'items_per_page=20' 'https://api.company-information.service.gov.uk/search/companies'
```

## Format
JSON search results with company number, title, status, type, creation or cessation dates, address, SIC-related description snippets and pagination metadata.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""Companies House company search -> pandas -> Parquet."""
import os
import requests
import pandas as pd

URL = "https://api.company-information.service.gov.uk/search/companies"
key = os.environ["COMPANIES_HOUSE_API_KEY"]
response = requests.get(
    URL,
    params={"q": "energy", "items_per_page": 20},
    auth=(key, ""),
    timeout=60,
)
response.raise_for_status()
payload = response.json()
df = pd.json_normalize(payload["items"], sep="_")
for column in ["date_of_creation", "date_of_cessation"]:
    if column in df.columns:
        df[column] = pd.to_datetime(df[column], errors="coerce")
df.to_parquet("companies_house_energy_search.parquet", index=False)
print(len(df), "companies of", payload["total_results"], "matches")
```
Not run: it needs a free API key.

## Limits
- Rate limit: 600 requests per 5 minutes.
- Search endpoints paginate with items_per_page and start_index.
- Searchable databases are not intended for bulk downloads; Companies House provides separate bulk data products.

## Quirks
- Company names are not stable identifiers; use company_number for joins and refresh records as filings change.
- Different resources expose different date fields and enumerated codes; retain the raw status and type values alongside normalized labels.
- The provider says the public information is not comprehensive and can contain inaccuracies or later corrections.
- Officer and control resources contain public-register personal information and require lawful downstream handling.

## Terms and attribution
- OGL v3 requires source acknowledgement and does not cover personal data, logos or third-party rights.
- Do not imply Companies House endorsement, and do not use automated access in a way that degrades the service.
- Terms page: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/

## Sources
- https://developer.company-information.service.gov.uk/: "The data returned is live and real-time, and is simple to use and understand."
- https://developer.company-information.service.gov.uk/developer-guidelines: "You can make up to 600 requests within a 5 minute period."
- https://www.gov.uk/guidance/search-the-companies-house-register: "This allows both consumers and technology providers access to real time updates on companies."
- https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/: "Contains public sector information licensed under the Open Government Licence v3.0."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.