companies-house-neo4j-python

A proof of concept app that stores the full graph network (officers, persons with significant control) of a UK company in Neo4j using the Companies House Public Data API.

Graph company data of Waterstones Booksellers Limited (00610095)

• companies-house-neo4j-python
  • Prerequisites
    • 1. Install Python 3 and uv
    • 2. Create a virtual environment with all necessary dependencies
    • 3. Create a .env file at the root of the project
    • 4. Optionally run a Neo4j database as a Docker container
  • Run application
  • Linting
  • Formatting

Prerequisites

• Python 3.13.*
• uv

1. Install Python 3 and uv

MacOS (using brew)

brew install [email protected] uv

Ubuntu/Debian

# Python
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13 python3.13-venv pipx
pipx ensurepath

# uv
pipx install uv

2. Create a virtual environment with all necessary dependencies

From the root of the project execute:

uv sync

3. Create a .env file at the root of the project

Generate an API key using the Companies House API guidelines.

# Companies House
COMPANIES_HOUSE_API_KEY="change_me"
COMPANIES_HOUSE_BASE_URL="https://api.company-information.service.gov.uk"

# Neo4j
NEO4J_URI="bolt://localhost:7687"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="your_password"

4. Optionally run a Neo4j database as a Docker container

docker compose up -d neo4j

Run application

uv run main.py COMPANY_NUMBER

Linting

uv run ruff check src/*

Formatting

uv run ruff format src/*