companies-house-codegen

A simple but powerful toolkit for downloading, compressing and formatting Companies House OpenAPI (Swagger 2.0) specifications.

Introduction

Companies House is an executive agency of the Department for Business and Trade, a department of the British Government. This official UK agency is responsible for incorperating and dissolving companies, and maintaining a register of information of limited companies (and some other companies) under the Companies Act and related legislation to be made available for public access.

Companies House hosts a JSON REST API called the Companies House API, which makes it possible for software developers to create application to retrieve information from Companies House's database (e.g. searching and retrieving public company data), as well as, interact with Companies House's database (e.g. manipulating company information, givem you have authority to do so). The full documentation for Companies House API can be found at the Companies House Developer Hub.

Unfortunately, the Companies House API does not come with an official SDK. Fortunately, the API is documented fully defined in OpenAPI (specifically Swagger 2.0) specifications - an open source standard for defining APIs. Since OpenAPI is industry standard there are many tools that exist that produce high quality SDKs from OpenAPI definitions. For example, Cloudflare, OpenAI, Anthropic and many define their SDKs in OpenAPI3 and generate them using Stainless. Unfortunately, these definitions are distributed amongst many files (i.e. the API is broken down into several smaller API products, with the Companies House Public Data API product by itself being distributed over 22 files!). Moreover, these definitions contain various errors that make them unusable.

This small, configurable and simple tool fetches the OpenAPI for Companies House API, formats them to fix errors found in them.

Getting Started

Requirements

companies-house-codegen requires Python 3.8+ and typing-extensions. You may also, optionally, install pydantic for additional typesafety.

Installation

pip is the default package installer for Python, enabling easy installation and management of packages from the Python Package Index (PyPI) and from Version Control System (VCS) sources via the command line.

[!TIP] The methods described work for other package manegers like uv and poetry

Install From PyPI

To this package from PyPI, run:

pip install companies-house-codegen

Install From Github (Using VCS Support)

To install from latest version of this Github repo use:

pip install git+https://github.com/MMurape/companies-house-codegen.git@main

[!TIP] See pip's documentation VCS Support for more infomation. Note, that most modern package managers also come with VCS support similar to pip.

Install From A Git Clone (Using a clone of this repo)

To install this repository from a git clone, perform the following steps:

1. Clone this repository.

2. After clone this repository, the run the following command:

   cd companies-house-codegen # change directory to this repository
   

3. Install the package using package manager of your choice:

   pip install .
   

Usage

This toolkit can either be used as a command-line interface - companies-house-codegen - or as a python module - companies_house_codegen.

For more information on command-line interface see: API Reference.

For more information on command-line interface see: CLI Reference.

Example: Download Companies House Public Data API and convert it to OpenAPI 3.0.1

As a simple example of usage, here is how you could download the OpenAPI (Swagger 2.0) specification for Companies House Public Data API and convert it to OpenAPI 3.0.1.

Using the CLI

# Download Companies House Public Data API and convert it to OpenAPI 3.0.1
companies-house-codegen -i https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/swagger.json --zip public_data_api_openapi.yml --openapi

Using the library

from companies_house_codegen.codegen import download_openapi
from companies_house_codegen.utils import mapping_representer
import yaml
from yaml import CDumper

public_data_api_openapi = download_openapi('https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/swagger.json')
with open('public_data_api_openapi.yml', 'w') as f:
    # yaml does not know how to dump special an Mappings like OrderedDict.
    CDumper.add_representer(OrderedDict, mapping_representer)
    yaml.dump(m, f, indent=2, sort_keys=False, Dumper=CDumper) # save yaml