Release of the new Python SDK for the German business registry

New Python SDK released for the German commercial register

Today we are excited to introduce our brand-new Python SDK for the Handelsregister.ai API. It makes it even easier to access structured company data from the German commercial register (Handelsregister) and use it in your Python projects. Whether you want to analyze financial reports, look up management information or enrich large datasets, this package brings all the key functions together in one lean, modern client.

What can the new package do?

• Simple search
  Find companies by name, location and other parameters.

• Financial data
  Access annual financial statements, financial KPIs and profit and loss statements.

• Management information
  Learn more about current and former executives, including their roles and terms of office.

• Detailed company data
  Get comprehensive information on legal form, status, register number, business purpose and more.

• Batch processing
  Use built-in functions to automatically enrich large datasets with up-to-date company data.

• Resilient design
  Built-in fault tolerance, retries and snapshot functionality mean you don't have to worry, even with complex requests.

Installation and getting started

Installation could hardly be simpler. You can install the package directly with pip:

pip install handelsregister

Then all you need to do is provide your API key from Handelsregister.ai, either as an environment variable or directly in your code:

export HANDELSREGISTER_API_KEY=your_api_key

Example 1: Quick start

With just a few lines of code, you can access company information right away:

from handelsregister import Handelsregister

## Create a client (API key from an environment variable or passed directly)
client = Handelsregister(api_key="your_api_key_here")

## Fetch company information
company_data = client.fetch_organization(q="Konux GmbH München")

## Example output
print(f"Company name: {company_data['name']}")
print(f"Register number: {company_data['registration']['register_number']}")
print(f"Status: {company_data['status']}")

This gives you key basic information instantly, ideal when you want a quick overview.

Example 2: Object-oriented usage

If you prefer working with object instances, the SDK offers a particularly convenient class interface:

from handelsregister import Company

## Create a Company object with the features you need
company = Company(
    "BMW AG München",
    features=[
        "related_persons",       # Management information
        "financial_kpi",         # Financial KPIs
        "balance_sheet_accounts" # Balance sheet data
    ]
)

## Basic information
print(f"Name: {company.name}")
print(f"Register number: {company.registration_number}")
print(f"Status: {'Active' if company.is_active else 'Inactive'}")
print(f"Address: {company.formatted_address}")

## Management information
for person in company.current_related_persons:
    print(f"Manager: {person['name']} - {person['role']['en']['long']}")

## Financial data for the most recent year
years = company.financial_years
if years:
    recent_year = years[0]
    revenue = company.get_financial_kpi_for_year(recent_year, "revenue")
    employees = company.get_financial_kpi_for_year(recent_year, "employees")
    print(f"Revenue ({recent_year}): {revenue}")
    print(f"Employees ({recent_year}): {employees}")

This approach works particularly well if you need to access the same company data repeatedly or work with several objects for different companies side by side.

Example 3: Batch processing and data enrichment

When you want to process many records at once, the SDK can save you a lot of time. With the built-in enrich method, you can automatically enrich an entire list of companies (for example, from a JSON file):

from handelsregister import Handelsregister
import json

## Sample data
data = [
    {"company_name": "BMW AG", "city": "München"},
    {"company_name": "Konux GmbH", "city": "München"},
    {"company_name": "OroraTech GmbH", "city": "Walldorf"}
]

## Save to a JSON file (optional)
with open("companies.json", "w") as f:
    json.dump(data, f)

## Create a client
client = Handelsregister()

## Enrich the data
client.enrich(
    file_path="companies.json",
    input_type="json",
    query_properties={
        "name": "company_name",  # 'company_name' is mapped to the query field 'name'
        "location": "city"       # 'city' is mapped to the query field 'location'
    },
    snapshot_dir="snapshots",   # Save intermediate results
    params={
        "features": ["related_persons", "financial_kpi"],
        "ai_search": "off"
    }
)

This lets you add up-to-date financial and management data to large lists of companies, for example, without querying each company individually. Thanks to snapshotting, you don't have to worry if a process is interrupted.

Features and properties at a glance

If you are wondering exactly which data you can retrieve, the SDK offers feature flags that let you specify precisely which information you want to receive:

In addition, the Company class provides numerous properties:

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

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

## Contact and address
company.address
company.formatted_address
company.coordinates
company.website
company.phone_number

## Financial data
company.financial_kpi
company.financial_years
company.balance_sheet_accounts
company.profit_and_loss_account

## Management
company.current_related_persons
company.past_related_persons
company.get_related_persons_by_role("MANAGING_DIRECTOR")

## Helper methods
company.get_financial_kpi_for_year(2022)
company.get_balance_sheet_for_year(2022)
company.get_profit_and_loss_for_year(2022)

Why is it worth using?

The Handelsregister Python SDK saves you time and frustration when you want to process data from the German commercial register. Instead of struggling through unstructured documents or building your own interfaces, you can now rely on a well-documented, robust library. You get access to management data, financial figures and plenty of other company information, all through a single, easy-to-use API.

For projects in data analysis, business intelligence or automation, this package adds real value, because you can conveniently query several companies and process the results directly. That makes it easier to create reports, monitor market participants or carry out background research, for example.

License and outlook

The Python SDK is released under the MIT License, which gives you as much flexibility in using it as possible. Feel free to take a look at the source code on GitHub, open issues or contribute pull requests to its further development.

We hope you enjoy trying it out, and we look forward to your feedback! If you have questions or need help getting started, take a look at the GitHub documentation or get in touch with us. With your help, we can keep improving the package and tailor it even better to your needs.

The Handelsregister.ai team wishes you every success with your projects!

Related guides

• Company Data via API – Instant Access to the German Commercial Register with handelsregister.ai
• Build a B2B company list in Excel with WZ filters and the API