handelsregister 0.4.0

Python SDK für den Zugriff auf die Handelsregister AI API

🔍 Handelsregister Python SDK

A modern Python client for the Handelsregister.ai API. Structured, reliable, and fast access to the German commercial register (Handelsregister): company master data, financials, management, shareholders, UBOs, person profiles, and official PDF documents.

✨ Features

• 🔎 Company lookup — fetch-organization with configurable feature flags
• 👤 Person profiles — fetch-person (Handelsregister roles + web data)
• 🗂️ Search — paginated search-organizations with postal-code filter
• 📊 Financial data — KPIs, balance sheet, P&L, full annual reports (MD/HTML)
• 👥 Management — current and past related persons with roles
• 🤝 Shareholders, UBOs, shareholdings — who owns the company, who the company owns
• 📰 News, publications, insolvency publications
• 🌐 Website content — structured Markdown, optimized for LLMs
• 📄 Document downloads — Gesellschafterliste, Gesellschaftsvertrag, AD, CD
• 🔐 Auth — x-api-key header or Bearer token, plus token management
• 📚 Batch enrichment — resilient CSV/JSON/XLSX enrichment with snapshots
• ⚡ Live mode — opt-in realtime lookups against the Handelsregister

📦 Installation

pip install handelsregister

🔑 Authentication

You can authenticate in two ways:

API key (recommended for server-to-server):

export HANDELSREGISTER_API_KEY=your_api_key_here

from handelsregister import Handelsregister

client = Handelsregister(api_key="your_api_key_here")

Bearer token (fine-grained control, expiration):

export HANDELSREGISTER_BEARER_TOKEN=your_token_here

client = Handelsregister(bearer_token="your_token_here")

When both are provided, the bearer token wins.

🚀 Quick Start

Company lookup

from handelsregister import Handelsregister

client = Handelsregister()

result = client.fetch_organization(
    q="KONUX GmbH München",
    features=["related_persons", "financial_kpi", "shareholders"],
    ai_search="on-default",          # optional: enable AI search
    # realtime_mode="handelsregister-default",  # +10 credits for live data
)

print(result["name"], result["registration"]["register_number"])

Object-oriented Company interface

from handelsregister import Company

company = Company(
    "OroraTech GmbH München",
    features=[
        "related_persons",
        "financial_kpi",
        "balance_sheet_accounts",
        "shareholders",
        "ubos",
        "shareholdings",
        "annual_financial_statements",
        "news",
    ],
)

print(company.name, company.is_active)
print(company.formatted_address)

# Management
for person in company.current_related_persons:
    print(person["name"], "-", person["role"]["en"]["long"])

# Shareholders (who owns the company)
for entry in company.shareholders.entries:
    print(entry.display_name, entry.percentage)

# Ultimate beneficial owners
for ubo in company.ubos.resolved:
    print(ubo.name, ubo.percentage)

# Outbound shareholdings (what the company owns)
for holding in company.shareholdings.current:
    print(holding.organization_name, holding.percentage)

# News
for article in company.news:
    print(article["publication_date"], article["title"])

Person profiles

The /v1/fetch-person endpoint merges Handelsregister records with public web data. ai_search is always on for this endpoint (the 15-credit base cost includes the AI enrichment). organization_q is required to disambiguate common names.

from handelsregister import Person

person = Person(
    person_q="Max Mustermann",
    organization_q="Beispielwerk Analytics GmbH",
    features=["shareholdings"],  # +5 credits, only if data is returned
)

print(person.canonical_name, "-", person.home_city)
print(person.bio)

for role in person.handelsregister_roles:
    print(role["name"], role["label"], role.get("start_date"), role.get("end_date"))

for holding in person.shareholdings.current:
    print(holding.organization_name, holding.percentage, holding.as_of)

Search

client = Handelsregister()

page = client.search_organizations(
    q="tech",
    limit=10,
    skip=0,
    filters={"postal_code": "80992"},
)

print(page["total"])
for item in page["results"]:
    print(item["name"], item["registration"]["register_number"])

📄 Document Downloads

from handelsregister import Handelsregister, Company

client = Handelsregister()

# Get the company's entity_id
result = client.fetch_organization(q="KONUX GmbH München")
entity_id = result["entity_id"]

# Download documents directly from the client
client.fetch_document(
    company_id=entity_id,
    document_type="shareholders_list",       # Gesellschafterliste
    output_file="konux_shareholders.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="articles_of_association", # Gesellschaftsvertrag / Satzung
    output_file="konux_articles.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="AD",                      # Aktueller Ausdruck
    output_file="konux_current.pdf",
)

pdf_bytes = client.fetch_document(
    company_id=entity_id,
    document_type="CD",                      # Chronologischer Ausdruck
)

# Or via the Company helper
company = Company("OroraTech GmbH München")
company.fetch_document(
    document_type="shareholders_list",
    output_file="ororatech_shareholders.pdf",
)

Available document types

Document Type	Description
shareholders_list	Gesellschafterliste
articles_of_association	Gesellschaftsvertrag / Satzung / Statut
AD	Aktuelle Daten (current excerpt)
CD	Chronologische Daten (historical excerpt)

🔐 Bearer Token Management

If you prefer managing bearer tokens over sharing an API key:

client = Handelsregister(api_key="your_api_key_here")

# Create a new token
created = client.create_token(
    token_name="My Application",
    abilities=["*"],
    expires_at="2026-01-01 00:00:00",
)
print(created)

# List / revoke
tokens = client.list_tokens()
client.revoke_token(token_id=42)
client.revoke_all_tokens()

📊 Data Enrichment

Enrich a CSV/JSON/XLSX file of companies with Handelsregister data. Intermediate snapshots let you resume long-running jobs.

from handelsregister import Handelsregister

client = Handelsregister()

client.enrich(
    file_path="companies.csv",
    input_type="csv",
    query_properties={
        "name": "company_name",   # map 'company_name' column to query
        "location": "city",       # map 'city' column to query
    },
    snapshot_dir="snapshots",
    params={
        "features": ["related_persons", "financial_kpi", "ubos"],
        "ai_search": "on-default",
    },
    output_format="csv",
)

There is also a DataFrame convenience:

import pandas as pd
from handelsregister import Handelsregister

client = Handelsregister()
df = pd.read_csv("companies.csv")
enriched = client.enrich_dataframe(
    df,
    query_properties={"name": "company_name", "location": "city"},
    params={"features": ["financial_kpi"]},
)

🖥️ Command Line Interface

Installing the package exposes the handelsregister CLI. If the optional rich dependency is installed, commands render colorful tables.

# Company lookup (defaults: all standard features + AI search)
$ handelsregister fetch "KONUX GmbH München"

# Raw JSON
$ handelsregister fetch json "KONUX GmbH München"

# Opt-in to realtime mode for live register data
$ handelsregister fetch "KONUX GmbH München" --realtime-mode handelsregister-default

# Person profile
$ handelsregister person \
    --person "Max Mustermann" \
    --organization "Beispielwerk Analytics GmbH" \
    --feature shareholdings

# Search
$ handelsregister search "tech" --postal-code 80992 --limit 20

# Enrich a file
$ handelsregister enrich companies.csv --input csv \
    --query-properties name=company_name location=city \
    --snapshot-dir snapshots \
    --feature related_persons --feature financial_kpi \
    --output-format csv

# Download documents
$ handelsregister document "KONUX GmbH München" \
    --type shareholders_list --output konux_shareholders.pdf

$ handelsregister document "KONUX GmbH München" \
    --type articles_of_association --output konux_articles.pdf

📋 Available Features (fetch-organization)

Feature Flag	Description
related_persons	Current and past management
financial_kpi	Yearly revenue, net income, employees, …
balance_sheet_accounts	Hierarchical balance sheet data
profit_and_loss_account	Profit & loss statements
annual_financial_statements	Full annual reports as Markdown
annual_financial_statements__html	Full annual reports as HTML
publications	Official Handelsregister publications
insolvency_publications	Insolvency court publications
news	News articles about the company
website_content	Company website as structured Markdown (AI mode, 0 credits)
shareholders (beta)	Shareholders with capital contribution and ratio
ubos (beta)	Ultimate beneficial owners (resolved / unresolved / coverage)
shareholdings (beta)	Outbound shareholdings (what the company owns in others)

realtime_mode="handelsregister-default" forces a live Handelsregister lookup (+10 credits), independent of the feature flags above.

🔍 Company properties

# Basic
company.name
company.entity_id
company.status
company.is_active
company.purpose

# Registration
company.registration_number
company.registration_court
company.registration_type
company.registration_date

# Contact & address
company.address
company.formatted_address
company.coordinates
company.website
company.phone_number
company.email

# Financial
company.financial_kpi
company.financial_years
company.balance_sheet_accounts
company.profit_and_loss_account
company.annual_financial_statements
company.annual_financial_statements_html
company.get_financial_kpi_for_year(2023)
company.get_balance_sheet_for_year(2023)
company.get_profit_and_loss_for_year(2023)
company.get_annual_financial_statement_for_year(2023)  # Markdown
company.get_annual_financial_statement_for_year(2023, html=True)

# People & ownership
company.current_related_persons
company.past_related_persons
company.get_related_persons_by_role("MANAGING_DIRECTOR")
company.shareholders           # ShareholderInfo
company.ubos                   # UBOInfo
company.shareholdings          # ShareholdingsInfo

# News & publications
company.publications
company.insolvency_publications
company.news
company.website_content

👤 Person properties

person.entity_id
person.name
person.canonical_name
person.given_name
person.family_name
person.previous_names
person.birth_date
person.home_city
person.bio
person.expertise
person.emails
person.phones
person.linkedin
person.github

person.handelsregister_roles
person.current_handelsregister_roles
person.get_handelsregister_roles_by_label("MANAGING_DIRECTOR")
person.affiliations

person.shareholdings           # PersonShareholdings (requires feature flag)

📜 License

MIT — see LICENSE.