API Referenz

Zugriff auf umfassende deutsche Unternehmensdaten über unsere RESTful API. Echtzeitinformationen aus offiziellen Handelsregistern.

Basis-URL

https://handelsregister.ai/api

Format

JSON

Authentifizierung

API Schlüssel

Rate Limits

60/min (5/min Dokumente)

Authentifizierung

Authentifizieren Sie Anfragen durch Einbindung Ihres API-Schlüssels als URL-Parameter api_key.

curl https://handelsregister.ai/api/v1/fetch-organization?api_key=your_api_key_here&q=company

import requests

url = "https://handelsregister.ai/api/v1/fetch-organization"
params = {
    "api_key": "your_api_key_here",
    "q": "company"
}

response = requests.get(url, params=params)
data = response.json()

const url = new URL('https://handelsregister.ai/api/v1/fetch-organization');
url.searchParams.append('api_key', 'your_api_key_here');
url.searchParams.append('q', 'company');

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

Endpunkte

GET

/v1/fetch-organization

5-21 Credits • 60/min

Umfassende Informationen über ein deutsches Unternehmen abrufen, einschließlich Rechtsstatus, Finanzdaten, Management und mehr.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	ERFORDERLICH	Ihr API-Authentifizierungsschlüssel
q	string	ERFORDERLICH	Firmenname, Registernummer oder Suchanfrage
feature	string	optional	Zusätzliches Datenfeature zum Einbeziehen. Kann mehrfach angegeben werden (siehe Features-Tabelle unten)
ai_search	string	optional	KI-Suche aktivieren. Werte: `on-default` oder Parameter komplett weglassen

Verfügbare Features

financial_kpi 1 Credit

balance_sheet_accounts 3 Credits

profit_and_loss_account 3 Credits

related_persons 2 Credits

publications 1 Credit

news 10 Credits

insolvency_publications 1 Credit

annual_financial_statements 5 Credits

Beispiel-Anfrage

curl 'https://handelsregister.ai/api/v1/fetch-organization?api_key=your_api_key_here&q=BMW%20AG&feature=financial_kpi&feature=related_persons&feature=publications&ai_search=on-default'

import requests

url = "https://handelsregister.ai/api/v1/fetch-organization"
params = {
    "api_key": "your_api_key_here",
    "q": "BMW AG",
    "feature": ["financial_kpi", "related_persons", "publications"],
    "ai_search": "on-default"
}

response = requests.get(url, params=params)
data = response.json()

const url = new URL('https://handelsregister.ai/api/v1/fetch-organization');
url.searchParams.append('api_key', 'your_api_key_here');
url.searchParams.append('q', 'BMW AG');
url.searchParams.append('feature', 'financial_kpi');
url.searchParams.append('feature', 'related_persons');
url.searchParams.append('feature', 'publications');
url.searchParams.append('ai_search', 'on-default');

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

Beispiel-Antwort

{
  "entity_id": "add84642a957b08a3f252c69c9d063de",
  "name": "Polyden-Folienfabrik GmbH",
  "status": "INACTIVE",
  "legal_form": "GmbH",
  "purpose": "Herstellung von Folien...",
  "registration_date": "1978-02-23T00:00:00",
  "address": {
    "house_number": "38",
    "street": "Ansbacher Straße",
    "postal_code": "91560",
    "city": "Heilsbronn",
    "coordinates": {
      "latitude": 49.33438,
      "longitude": 10.78262
    }
  },
  "registration": {
    "court": "Ansbach",
    "register_type": "HRB",
    "register_number": "405"
  },
  "contact_data": {
    "website": "https://www.polyden.de",
    "phone_number": "+49 9872 808 0"
  },
  "financial_kpi": [
    {
      "year": 2022,
      "revenue": 41855558.25,
      "net_income": -19668989.99,
      "employees": 208
    }
  ],
  "related_persons": {
    "current": [
      {
        "name": "Knut Neumann",
        "role": {
          "en": {"long": "Managing Director"},
          "de": {"long": "Geschäftsführer"}
        },
        "start_date": "2019-06-03"
      }
    ]
  },
  "publications": [...],
  "news": [
    {
      "title": "Company News Title",
      "source": "News Source",
      "publication_date": "2023-08-08"
    }
  ],
  "meta": {
    "request_credit_cost": 55,
    "credits_remaining": "73841334"
  }
}

Details der Antwortstruktur

Grundlegende Unternehmensdaten

Immer enthalten: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services

financial_kpi

Array jährlicher Finanzkennzahlen (Umsatz, Nettogewinn, Mitarbeiter, etc.) über mehrere Jahre

balance_sheet_accounts

Hierarchische Bilanzdaten mit Aufschlüsselung von Vermögen und Verbindlichkeiten pro Jahr

profit_and_loss_account

Detaillierte GuV-Aufstellungen mit Umsatz-, Ausgaben- und Gewinnaufschlüsselung pro Jahr

related_persons

Aktuelle und ehemalige Geschäftsführer/Vorstände mit Rollen, Namen und Amtszeiten

publications

Offizielle Handelsregisterveröffentlichungen und Bekanntmachungen

news

Array von Nachrichtenartikeln mit Titel, Quelle, Veröffentlichungsdatum und URL

insolvency_publications

Insolvenzgerichtsveröffentlichungen mit Daten, Aktenzeichen und Ereignisdetails

annual_financial_statements

Vollständige Jahresberichte im Markdown-Format mit Metadaten

GET

/v1/search-organizations

1 Credit • 60/min

Deutsche Unternehmen mit erweiterten Filter- und Paginierungsoptionen suchen.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	ERFORDERLICH	Ihr API-Authentifizierungsschlüssel
q	string	ERFORDERLICH	Suchanfrage (min: 2 Zeichen)
skip	integer	optional	Anzahl der zu überspringenden Ergebnisse (Standard: 0)
limit	integer	optional	Ergebnisse pro Seite (Standard: 10, max: 100)
filters	object	optional	Filter nur nach postal_code. Format: `{"postal_code": "80992"}`

Beispiel-Anfrage

curl 'https://handelsregister.ai/api/v1/search-organizations?api_key=your_api_key_here&q=tech&limit=10&filters=%7B%22postal_code%22%3A%2280992%22%7D'

import requests
import json

url = "https://handelsregister.ai/api/v1/search-organizations"
params = {
    "api_key": "your_api_key_here",
    "q": "tech",
    "limit": 10,
    "filters": json.dumps({"postal_code": "80992"})
}

response = requests.get(url, params=params)
data = response.json()

const url = new URL('https://handelsregister.ai/api/v1/search-organizations');
url.searchParams.append('api_key', 'your_api_key_here');
url.searchParams.append('q', 'tech');
url.searchParams.append('limit', '10');
url.searchParams.append('filters', JSON.stringify({"postal_code": "80992"}));

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

Beispiel-Antwort

{
  "results": [
    {
      "entity_id": "65063129c1bf565e4244b943a188bbda",
      "name": "m50 GmbH",
      "registration": {
        "court": "München",
        "register_type": "HRB",
        "register_number": "189767"
      },
      "address": {
        "house_number": "20",
        "street": "Gubestraße",
        "postal_code": "80992",
        "city": "München",
        "county": "München (Stadt)",
        "state": "Bayern",
        "country": "DEU",
        "coordinates": {
          "latitude": 48.18005,
          "longitude": 11.51116
        }
      },
      "registration_date": "2011-01-04T00:00:00",
      "purpose": "Film- und Fernsehproduktion..."
    }
  ],
  "total": 988,
  "meta": {
    "request_credit_cost": 1,
    "credits_remaining": "73841333"
  }
}

GET

/v1/fetch-document

5 Credits • 5/min

Offizielle PDF-Dokumente aus dem deutschen Handelsregister herunterladen.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	ERFORDERLICH	Ihr API-Authentifizierungsschlüssel
company_id	string	ERFORDERLICH	Eindeutige Unternehmens-Entity-ID aus Suchergebnissen
document_type	string	ERFORDERLICH	Dokumenttyp. Werte: `shareholders_list`, `AD`, `CD`

Beispiel-Anfrage

curl 'https://handelsregister.ai/api/v1/fetch-document?api_key=your_api_key_here&company_id=20a1510e88cd2e9b166db4d0bc5d563d&document_type=shareholders_list' \
  -o document.pdf

import requests

url = "https://handelsregister.ai/api/v1/fetch-document"
params = {
    "api_key": "your_api_key_here",
    "company_id": "20a1510e88cd2e9b166db4d0bc5d563d",
    "document_type": "shareholders_list"
}

response = requests.get(url, params=params)

# Save PDF file
with open("document.pdf", "wb") as f:
    f.write(response.content)

const url = new URL('https://handelsregister.ai/api/v1/fetch-document');
url.searchParams.append('api_key', 'your_api_key_here');
url.searchParams.append('company_id', '20a1510e88cd2e9b166db4d0bc5d563d');
url.searchParams.append('document_type', 'shareholders_list');

fetch(url)
  .then(response => response.blob())
  .then(blob => {
    const a = document.createElement('a');
    a.href = URL.createObjectURL(blob);
    a.download = 'document.pdf';
    a.click();
  });

Antwort

Erfolg (200): Gibt PDF-Datei direkt zurück

Content-Type: application/pdf

Fehler: Gibt JSON mit Fehlerdetails zurück

Dokumenttypen

shareholders_list

Gesellschafterliste-Dokument

AD

Aktuelle Auszüge (Aktuelle Daten)

CD

Historische Auszüge (Chronologische Daten)

Fehlerbehandlung

200 OK

Anfrage erfolgreich

400 Bad Request

Ungültige Parameter

401 Unauthorized

Ungültiger oder fehlender API-Schlüssel

402 Payment Required

Unzureichende Credits

429 Too Many Requests

Rate Limit überschritten

500 Server Error

Interner Serverfehler

Fehler-Antwortformat

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account has insufficient credits",
    "details": {
      "required": 10,
      "available": 5
    }
  }
}

Python SDK

PyPI GitHub v1.0.0 • Python 3.8+ • MIT Lizenz

Installation

pip install handelsregister

Grundlegende Nutzung

from handelsregister import Handelsregister

client = Handelsregister(api_key="your_key")
company = client.fetch_organization(q="BMW AG")

print(company['name'])
print(company['registration'])

Objekt-Interface

from handelsregister import Company

company = Company("BMW AG", features=[
    "financial_kpi",
    "related_persons"
])

print(company.revenue)
print(company.current_ceo)

Datenanreicherung

client.enrich(
    file_path="companies.csv",
    query_properties={"name": "company_name", "location": "city"},
    features=["financial_kpi", "related_persons"],
    output_format="json"
)

API Referenz

Authentifizierung

Endpunkte

/v1/fetch-organization

Parameter

Verfügbare Features

Beispiel-Anfrage

Beispiel-Antwort

Details der Antwortstruktur

Grundlegende Unternehmensdaten

financial_kpi

balance_sheet_accounts

profit_and_loss_account

related_persons

publications

news

insolvency_publications

annual_financial_statements

/v1/search-organizations

Parameter

Beispiel-Anfrage

Beispiel-Antwort

/v1/fetch-document

Parameter

Beispiel-Anfrage

Antwort

Dokumenttypen

Fehlerbehandlung

Fehler-Antwortformat

Python SDK

Grundlegende Nutzung

Objekt-Interface

Datenanreicherung

Cookie-Einstellungen

Cookie-Einstellungen anpassen