Σημεία Τέλους

GET

/v1/search-organizations

1 πίστωση • 60/λεπτό

Αναζήτηση γερμανικών εταιρειών με προηγμένο φιλτράρισμα και υποστήριξη σελιδοποίησης.

Παράμετροι

Όνομα	Τύπος	Απαιτείται	Περιγραφή
api_key	string	Υπό όρους*	Το κλειδί API σας. Απαιτείται εάν δεν χρησιμοποιείτε την κεφαλίδα x-api-key ή Bearer token
q	string	Υπό όρους*	Ερώτημα αναζήτησης (ελάχιστο: 2 χαρακτήρες)
skip	integer	προαιρετικό	Αριθμός αποτελεσμάτων προς παράλειψη (προεπιλογή: 0)
limit	integer	προαιρετικό	Αποτελέσματα ανά σελίδα (προεπιλογή: 10, μέγιστο: 30)
filters	string (JSON object)	προαιρετικό	Φιλτράρισμα μόνο κατά postal_code. Μορφή:
sort	string	προαιρετικό	Sortierfeld: relevance (Standard), registration_date, financial_year, revenue, profit, employees, total_assets, equity, liabilities, cash, equity_ratio, share_capital, last_activity, largest_share_ratio, management_size, md_oldest_birth_date, md_youngest_birth_date, fb_entity_id oder distance (erfordert den Geo-Filter). Ein unbekanntes Feld wird mit 422 beantwortet.
order	string	προαιρετικό	Sortierrichtung: asc oder desc. Jedes Sortierfeld hat eine sinnvolle Voreinstellung.
match_context	boolean	προαιρετικό	match_context=1 ergänzt jeden Treffer um _match_context: die Einträge, die die Registerdaten-Filter erfüllt haben. Ohne den Parameter bleibt die Antwort schlank.

Filter

Alle Filter sind optional. Bereichsfilter akzeptieren {"gte": min, "lte": max} — jede der beiden Grenzen kann entfallen — und werden in einem financial_filters-Objekt verschachtelt, z. B. {"financial_filters":{"pl_revenue":{"gte":1000000}}}.

Beispiel-URL

GET /v1/search-organizations?limit=10&filters={"city":"München","industry_code":["62.10.1","62.10.3"],"industry_scheme":"WZ2025","financial_filters":{"pl_revenue":{"gte":1000000}}}

Zur Lesbarkeit unkodiert dargestellt — in echten Requests muss der filters-Wert URL-kodiert sein.

Identität & Registrierung

registration_date_from date: Frühestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
registration_date_to date: Spätestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
legal_form_code string: Exakter Rechtsformcode, z. B. GmbH, AG, e.V. oder UG (haftungsbeschränkt). Erlaubt ist genau ein String; Arrays werden abgelehnt.
industry_code string / array: NACE-/WZ-Branchencode. Einzelner Code oder Array von Codes — ein Array findet Unternehmen aus jeder dieser Branchen, z. B. ["62.10.1","62.10.3"].
industry_scheme string: Klassifikationsschema zu industry_code. Standard: WZ2025.
active boolean: true = nur aktive Unternehmen, false = nur inaktive. Ohne Angabe: beide.
status enum: Exakter Registerstatus: ACTIVE, INACTIVE, TERMINATED, DISSOLVED oder INSOLVENT. Die Werte müssen großgeschrieben werden. Für einen konkreten Lebenszyklusstatus ist status gedacht; für die einfache Unterscheidung zwischen aktiv und inaktiv reicht active.
legal_form_liability_type enum: Haftungsform: limited, unlimited oder mixed.

Standort

postal_code string: Deutsche 5-stellige Postleitzahl (PLZ).
city string: Stadtname.
state string: Deutsches Bundesland (z. B. Bayern, Hessen).
location_coordinates object {lat, lon}: Mittelpunkt der Umkreissuche in WGS84-Dezimalgrad, angegeben als {"lat":48.137,"lon":11.576}. Der Breitengrad muss zwischen -90 und 90 liegen, der Längengrad zwischen -180 und 180. Nur zusammen mit location_max_distance_km senden.
location_max_distance_km number: Suchradius in Kilometern (1–100). Nur zusammen mit location_coordinates senden.

Gericht & Register

registration_type string / array: Registerart: HRA, HRB, GnR, PR oder VR. Einzelner Wert oder Array.
registration_authority_name string: Registergericht (z. B. München).
registration_number string: Registernummer (z. B. HRB 12345).

Größe & Mitarbeiter

company_size_category enum: Größenklasse: micro, small, medium oder large.
emp_count range: Bereich der Mitarbeiterzahl.

Bilanz

bs_assets_total EUR range: Bilanzsumme, in EUR.
bs_equity_total EUR range: Eigenkapital, in EUR.
bs_liabilities_total EUR range: Gesamtverbindlichkeiten, in EUR.
bs_cash_and_equivalents EUR range: Kassenbestand & Zahlungsmitteläquivalente, in EUR.
bs_cash_to_liabilities decimal range: Liquiditätsgrad (Kassenbestand ÷ Verbindlichkeiten), Dezimalwert.
bs_equity_ratio ratio (0–1): Eigenkapitalquote (Eigenkapital ÷ Bilanzsumme), Dezimalwert 0–1.
bs_debt_to_assets ratio (0–1): Fremdkapitalquote (Schulden ÷ Bilanzsumme), Dezimalwert 0–1.

Gewinn- und Verlustrechnung

pl_revenue EUR range: Jahresumsatz, in EUR.
pl_net_income EUR range: Jahresüberschuss, in EUR.
pl_ebit EUR range: EBIT / Betriebsergebnis, in EUR.

Registerdaten-Filter (Eigentum, Geschäftsführung, Insolvenz)

ownership_filters conditions: Eigentums- und Nachfolgekriterien aus dem Playground: structure, owner_managed, likely_family_owned, largest_share_ratio (0–1), oldest_owner_birth_date und youngest_owner_birth_date.
executive_filters conditions: Alterskriterien für die Geschäftsführung aus dem Playground: md_oldest_birth_date und md_youngest_birth_date.
lifecycle_filters conditions: Insolvenzkriterien aus dem Playground: insolvency_active, insolvency_status und insolvency_opened_date.

Jede Gruppe steht als Objekt in filters. Boolean-Felder akzeptieren true oder false. Für Datums- und Zahlenfelder sind gte, lte, gt, lt, eq und exists möglich. Datumsangaben können als JJJJ, JJJJ-MM oder JJJJ-MM-TT übergeben werden; Teilangaben decken den gesamten Zeitraum ab. Eigentumsanteile werden als Dezimalzahl zwischen 0 und 1 angegeben — 0.25 entspricht 25 %.

Registerdaten-Filter im Detail

Diese Eigentums-, Geschäftsführungs- und Insolvenzkriterien stehen im aktuellen Such-Playground auf der Startseite zur Verfügung — einschließlich KI-Suche und Schnellstarts. Jede Gruppe steht als eigenes Bedingungsobjekt im filters-Objekt und lässt sich mit allen übrigen Filtern kombinieren.

Voraussetzung ist ein aktives Pro- oder Max-Abo. Ohne passendes Abo antwortet die API mit HTTP 403 und error: subscription_required — meta.blocked_filters nennt die betroffenen Gruppen, meta.required_plans die möglichen Tarife. Ein gesperrter Filter wird nie stillschweigend entfernt, denn damit wäre die Suche unbemerkt eine andere.

`ownership_filters` Eigentümerstruktur

Ein Bedingungsobjekt

structure enum: Zusammensetzung des Eigentümerkreises. Werte: sole_person Eine Person · partners Mehrere Gesellschafter · sole_company Ein Unternehmen · family Familie · fragmented Breit gestreut · corporate_group Konzern
owner_managed boolean: Mindestens ein Eigentümer ist zugleich in der Geschäftsführung eingetragen.
likely_family_owned boolean: Mehrere Eigentümer teilen einen Familiennamen — ein Hinweis auf Familienbesitz, keine amtliche Feststellung.
largest_share_ratio range: Größter Einzelanteil, Dezimalwert zwischen 0 und 1.
oldest_owner_birth_date date: Geburtsdatum des ältesten Eigentümers.
youngest_owner_birth_date date: Geburtsdatum des jüngsten Eigentümers.

Treffer-Kontext: _match_context.ownership

`executive_filters` Führungs-Kennzahlen

Ein Bedingungsobjekt

md_oldest_birth_date date: Geburtsdatum des ältesten aktiven Geschäftsführers.
md_youngest_birth_date date: Geburtsdatum des jüngsten aktiven Geschäftsführers.

Treffer-Kontext: _match_context.executive

`lifecycle_filters` Lebenszyklus & Insolvenz

Ein Bedingungsobjekt

insolvency_active boolean: true = laufendes Verfahren. Das Feld ist nur gesetzt, wenn überhaupt ein Verfahren erfasst ist — {"exists": false} findet daher Unternehmen ganz ohne Insolvenzverfahren.
insolvency_status enum: Stand des jüngsten Verfahrens. Werte: opened Eröffnet · provisional Vorläufig · discontinued Eingestellt · concluded Abgeschlossen · rejected_no_assets Mangels Masse abgewiesen · plan_monitoring Planüberwachung · opening_rescinded Eröffnung aufgehoben
insolvency_opened_date date: Datum der Verfahrenseröffnung.

Treffer-Kontext: _match_context.lifecycle

Jedes Feld akzeptiert einen Einzelwert, eine Liste (einer der Werte genügt) oder ein Operator-Objekt mit gte, lte, gt, lt, eq oder exists. Datumsangaben als JJJJ, JJJJ-MM oder JJJJ-MM-TT; eine Teilangabe deckt ihren gesamten Zeitraum ab. Anteile reisen als Dezimalwert zwischen 0 und 1 — 0.25 entspricht 25 %.

Mit match_context=1 nennt jeder Treffer unter _match_context die Einträge, die den Filter erfüllt haben — jede Gruppe unter ihrem eigenen Schlüssel.

Beispiel: familien- und inhabergeführte Unternehmen, deren ältester Eigentümer 1959 oder früher geboren wurde

GET /v1/search-organizations?limit=10&match_context=1&filters={"state":"Bayern","ownership_filters":{"owner_managed":true,"likely_family_owned":true,"oldest_owner_birth_date":{"lte":"1959"}}}

Zur Lesbarkeit unkodiert dargestellt — in echten Requests muss der filters-Wert URL-kodiert sein.

Auszug aus der Antwort

{
  "name": "Muster Beteiligungs-GmbH",
  "_match_context": {
    "ownership": {
      "owner_managed": true,
      "likely_family_owned": true,
      "oldest_owner_birth_date": "1948-04-29"
    }
  }
}

Namen und Kennungen sind im Beispiel ersetzt.

Παράδειγμα Αιτήματος

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));

Παράδειγμα Απάντησης

{
  "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"
  }
}

/v1/search-organizations

Παράμετροι

Filter

Identität & Registrierung

Standort

Gericht & Register

Größe & Mitarbeiter

Bilanz

Gewinn- und Verlustrechnung

Registerdaten-Filter (Eigentum, Geschäftsführung, Insolvenz)

Registerdaten-Filter im Detail

ownership_filters Eigentümerstruktur

executive_filters Führungs-Kennzahlen

lifecycle_filters Lebenszyklus & Insolvenz

Auszug aus der Antwort

Παράδειγμα Αιτήματος

Παράδειγμα Απάντησης

Ρυθμίσεις cookies

Προσαρμογή ρυθμίσεων cookies

`ownership_filters` Eigentümerstruktur

`executive_filters` Führungs-Kennzahlen

`lifecycle_filters` Lebenszyklus & Insolvenz