Das neue Python Package für das Handelsregister

Neues Python-Paket für den Zugriff auf das Handelsregister veröffentlicht

Wir freuen uns, dir heute unser brandneues Python SDK für die Handelsregister.ai-API vorzustellen. Damit kannst du ab sofort noch einfacher auf strukturierte Firmendaten des deutschen Handelsregisters zugreifen und sie in deinen Python-Projekten nutzen. Ob du Finanzberichte analysieren, Management-Informationen abfragen oder große Datensätze anreichern möchtest – mit diesem Paket hast du alle wichtigen Funktionen in einem schlanken, modernen Client vereint.

Was kann das neue Paket?

• Einfache Suche
  Finde Unternehmen anhand von Namen, Standorten und weiteren Parametern.

• Finanzdaten
  Greife auf Jahresabschlüsse, Finanz-KPIs und Gewinn- und Verlustrechnungen zu.

• Management-Informationen
  Erfahre mehr über aktuelle und ehemalige Führungskräfte, inklusive Rollen und Amtszeiten.

• Detaillierte Firmendaten
  Erhalte umfassende Informationen zu Rechtsform, Status, Registernummer, Unternehmenszweck und mehr.

• Batch Processing
  Nutze integrierte Funktionen, um große Datenbestände automatisiert mit aktuellen Firmendaten anzureichern.

• Resilientes Design
  Dank eingebauter Fehlertoleranz, Retries und Snapshot-Funktionalitäten musst du dir auch bei komplexen Anfragen keine Sorgen machen.

Installation und erster Einstieg

Die Installation ist denkbar einfach. Du kannst das Paket direkt über pip installieren:

pip install handelsregister

Anschließend musst du nur noch deinen API-Key von Handelsregister.ai hinterlegen – entweder als Umgebungsvariable oder direkt im Code:

export HANDELSREGISTER_API_KEY=dein_api_key

Beispiel 1: Schneller Start (Quick Start)

Mit nur wenigen Zeilen Code kannst du direkt auf Unternehmensinformationen zugreifen:

from handelsregister import Handelsregister

# Client erstellen (API-Key aus Umgebungsvariable oder direkt übergeben)
client = Handelsregister(api_key="dein_api_key_here")

# Unternehmensinformationen abrufen
company_data = client.fetch_organization(q="Konux GmbH München")

# Beispielausgabe
print(f"Unternehmensname: {company_data['name']}")
print(f"Registernummer: {company_data['registration']['register_number']}")
print(f"Status: {company_data['status']}")

Damit stehen dir sofort wichtige Basisinformationen zur Verfügung – ideal, wenn du schnell einen Überblick bekommen willst.

Beispiel 2: Objektorientierte Nutzung

Wenn du lieber mit Objektinstanzen arbeiten möchtest, bietet das SDK eine besonders praktische Klassenschnittstelle:

from handelsregister import Company

# Company-Objekt mit gewünschten Features anlegen
company = Company(
    "BMW AG München",
    features=[
        "related_persons",       # Managementinformationen
        "financial_kpi",         # Finanz-KPIs
        "balance_sheet_accounts" # Bilanzdaten
    ]
)

# Basisinformationen
print(f"Name: {company.name}")
print(f"Registernummer: {company.registration_number}")
print(f"Status: {'Aktiv' if company.is_active else 'Inaktiv'}")
print(f"Adresse: {company.formatted_address}")

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

# Finanzdaten für das aktuellste Jahr
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"Umsatz ({recent_year}): {revenue}")
    print(f"Mitarbeiter ({recent_year}): {employees}")

Diese Herangehensweise eignet sich besonders, wenn du wiederholt auf dieselben Unternehmensdaten zugreifen willst oder mehrere Objekte für verschiedene Firmen nebeneinander benötigst.

Beispiel 3: Batch Processing & Datenanreicherung

Gerade wenn du viele Datensätze gleichzeitig verarbeiten möchtest, kann das SDK eine große Zeitersparnis sein. Mit der integrierten enrich-Methode lässt sich eine ganze Liste von Firmen (zum Beispiel aus einer JSON-Datei) automatisch anreichern:

from handelsregister import Handelsregister
import json

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

# In eine JSON-Datei speichern (optional)
with open("companies.json", "w") as f:
    json.dump(data, f)

# Client erstellen
client = Handelsregister()

# Daten anreichern
client.enrich(
    file_path="companies.json",
    input_type="json",
    query_properties={
        "name": "company_name",  # 'company_name' wird zur Abfrage 'name' gemappt
        "location": "city"       # 'city' wird zur Abfrage 'location' gemappt
    },
    snapshot_dir="snapshots",   # Zwischenergebnisse speichern
    params={
        "features": ["related_persons", "financial_kpi"],
        "ai_search": "off"
    }
)

Auf diese Weise kannst du beispielsweise große Listen von Unternehmen mit aktuellen Finanz- und Managementdaten ergänzen, ohne jede Firma einzeln abzufragen. Dank Snapshotting musst du dir keine Sorgen machen, wenn ein Prozess mal unterbrochen wird.

Features und Properties im Überblick

Falls du dich fragst, welche Daten konkret abrufbar sind, bietet das SDK Feature Flags, mit denen du genau festlegen kannst, welche Informationen du erhalten möchtest:

Zusätzlich stellt die Company-Klasse zahlreiche Properties zur Verfügung:

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

# Registrierungsinfos
company.registration_number
company.registration_court
company.registration_type
company.registration_date

# Kontakt und Adresse
company.address
company.formatted_address
company.coordinates
company.website
company.phone_number

# Finanzdaten
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")

# Methoden-Helfer
company.get_financial_kpi_for_year(2022)
company.get_balance_sheet_for_year(2022)
company.get_profit_and_loss_for_year(2022)

Warum lohnt sich der Einsatz?

Mit dem Handelsregister Python SDK sparst du Zeit und Nerven, wenn du Daten aus dem deutschen Handelsregister verarbeiten möchtest. Anstatt dich durch unstrukturierte Dokumente zu kämpfen oder eigene Schnittstellen zu bauen, kannst du jetzt auf eine gut dokumentierte, robuste Bibliothek zurückgreifen. Du erhältst Zugriff auf Managementdaten, Finanzkennzahlen und viele weitere Unternehmensinformationen – alles über eine einzige, einfach zu verwendende API.

Für Projekte im Bereich Datenanalyse, Business Intelligence oder Automatisierung ist dieses Paket ein echter Mehrwert, da du bequem mehrere Unternehmen abfragen und die Ergebnisse direkt weiterverarbeiten kannst. Das erleichtert dir zum Beispiel das Erstellen von Berichten, das Monitoring von Marktteilnehmern oder die Durchführung von Hintergrundrecherchen.

Lizenz und Ausblick

Das Python SDK steht unter einer MIT-Lizenz, was dir eine möglichst flexible Nutzung erlaubt. Schau dir gern den Quellcode auf GitHub an, stelle Issues ein oder trage mit Pull Requests zur Weiterentwicklung bei.

Wir hoffen, du hast Spaß beim Ausprobieren und freuen uns auf dein Feedback! Falls du Fragen hast oder Hilfe beim Einstieg brauchst, wirf einen Blick in die GitHub-Dokumentation oder schreib uns. Mit deiner Hilfe können wir das Paket kontinuierlich verbessern und noch besser auf deine Bedürfnisse zuschneiden.

Viel Erfolg bei deinen Projekten wünscht dir das Handelsregister.ai-Team!