v1.0.0 安定版
ダッシュボード

APIリファレンス

RESTful APIを通じてドイツ企業の包括的なデータにアクセスします。公式商業登記からのリアルタイム情報。

ベースURL
https://handelsregister.ai/api
形式
JSON
認証
APIキー
レート制限
60回/分（文書は5回/分）

認証

Handelsregister AI APIは2つの認証方法をサポートしています：APIキーとBearerトークン。両方の方法はすべてのAPIエンドポイントで機能します。

認証方法

1. APIキー認証

APIキーは2つの方法で提供できます：

a)
ヘッダー（推奨）： x-api-key: YOUR_API_KEY
b)
クエリパラメータ（レガシー）： ?api_key=YOUR_API_KEY

2. Bearerトークン認証

セキュリティの強化とトークン管理のために、APIトークンを作成できます：

認証ヘッダー： Authorization: Bearer YOUR_TOKEN

ベストプラクティスと使用例

ヘッダー経由のAPIキー： サーバー間統合と本番環境での使用に推奨
クエリパラメータ経由のAPIキー： クイックテストと下位互換性のためのみ
Bearerトークン： 細かいアクセス制御、トークンの有効期限、強化されたセキュリティが必要なアプリケーションに最適

APIキー認証の例

x-api-keyヘッダーの使用（推奨） 
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "x-api-key: YOUR_API_KEY"
# Using query parameter (legacy)
curl "https://handelsregister.ai/api/v1/fetch-organization?api_key=YOUR_API_KEY&q=company"

# Using x-api-key header (recommended)
curl -X GET "https://handelsregister.ai/api/v1/fetch-organization?q=company" \
     -H "x-api-key: YOUR_API_KEY"

Bearerトークン管理

APIトークンの作成
curl -X POST "https://handelsregister.ai/api/v1/auth/tokens/create" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "token_name": "My Application",
       "abilities": ["*"],
       "expires_at": "2026-01-01 00:00:00"
     }'

レスポンスにはBearerトークンが含まれます。安全に保管してください！

Bearerトークンの使用
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
トークン管理エンドポイント
  • POST /api/v1/auth/tokens/create - 新しいトークンを作成
  • GET /api/v1/auth/tokens - すべてのトークンを一覧表示
  • DELETE /api/v1/auth/tokens/{id} - 特定のトークンを取り消す
  • DELETE /api/v1/auth/tokens - すべてのトークンを取り消す

エンドポイント

GET

/v1/fetch-organization

5-21クレジット • 60回/分

法的地位、財務データ、経営陣など、ドイツ企業の包括的な情報を取得します。

パラメータ

名前 タイプ 必須 説明
api_key string 条件付き* あなたのAPIキー。x-api-keyヘッダーまたはBearerトークンを使用していない場合は必須
q string 必須 企業名、登録番号、または検索クエリ
feature string オプション 含める追加データ機能。複数回指定可能（下記の機能テーブルを参照）
ai_search string オプション AI検索を有効にします。値： on-default または完全にパラメータを省略
realtime_mode string オプション Echtzeitmodus für Live-Daten aus dem Handelsregister aktivieren. Werte: handelsregister-default oder Parameter komplett weglassen

利用可能な機能

financial_kpi 1クレジット
balance_sheet_accounts 3クレジット
profit_and_loss_account 3クレジット
related_persons 2クレジット
publications 1クレジット
news 10クレジット
insolvency_publications 1クレジット
annual_financial_statements 5クレジット
annual_financial_statements__html 5 Credits
shareholders Beta
5クレジット
ubos Beta
10 Credits
shareholdings Beta
5 Credits
website_content AI
0 Credits

リクエスト例

curl -X GET 'https://handelsregister.ai/api/v1/fetch-organization?q=BMW%20AG&feature=financial_kpi&feature=related_persons&feature=publications&feature=website_content&ai_search=on-default' \
     -H 'x-api-key: YOUR_API_KEY'

レスポンス例

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

レスポンス構造の詳細

企業の基本データ

常に含まれます： entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services

financial_kpi

複数年にわたる年次財務指標の配列（売上高、純利益、従業員数など）

balance_sheet_accounts

年ごとの資産と負債の内訳を含む階層型貸借対照表データ

profit_and_loss_account

年ごとの売上、費用、利益の内訳を含む詳細な損益計算書

related_persons

役職、名前、在任期間を含む現在および過去の取締役/役員

publications

公式の商業登記の出版物および発表

news

タイトル、ソース、公開日、URLを含むニュース記事の配列

insolvency_publications

日付、ケースID、イベントの詳細を含む破産裁判所の出版物

annual_financial_statements

メタデータ付きのmarkdown形式の完全な年次報告書

annual_financial_statements__html

Vollständige Jahresberichte im HTML-Format mit Metadaten

shareholders Beta

所有率と役割を含む会社の株主リスト

ubos Beta

Wirtschaftlich Berechtigte (UBOs) mit Beteiligungsquoten, inklusive aufgelöster und nicht aufgelöster Eigentümer sowie Abdeckungsgrad

shareholdings Beta

Aktuelle Beteiligungen dieses Unternehmens an anderen Gesellschaften mit Anteilshöhe, Einlage und Stichtag

website_content

Unternehmens-Website als strukturiertes Markdown, optimiert für LLM-Verarbeitung (nur AI Mode, 0 Credits)

GET

/v1/fetch-person

15-20 Credits • 60/min

Personenprofile aus dem deutschen Handelsregister und dem öffentlichen Web zusammenführen. ai_search ist immer aktiv; die Grundkosten von 15 Credits enthalten die AI-Anreicherung bereits.

Parameter

名前 タイプ 必須 説明
api_key string 必須 あなたのAPIキー。x-api-keyヘッダーまたはBearerトークンを使用していない場合は必須
person_q string 必須 Name der Person (min. 2 Zeichen, erforderlich)
organization_q string 必須 Unternehmenskontext zur Disambiguierung gleichnamiger Personen (min. 2 Zeichen, erforderlich)
feature string[] オプション Zusätzliches Datenfeature. Zurzeit unterstützt: shareholdings.

Verfügbare Features

shareholdings +5 credits

Beteiligungen der Person an Unternehmen (Name, Anteil, Rolle, Stichtag). +5 Credits, nur wenn Daten geliefert werden.

Beispiel-Anfrage

curl -X GET 'https://handelsregister.ai/api/v1/fetch-person?person_q=Max%20Mustermann&organization_q=Beispielwerk%20Analytics%20GmbH&features=shareholdings' \
     -H 'x-api-key: YOUR_API_KEY'

Beispiel-Antwort

{
  "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
  "name": "Max Mustermann",
  "birth_date": "1985-07-14",
  "name_parts": {
    "given": "Max",
    "family": "Mustermann",
    "maiden": null,
    "canonical_name": "Mustermann, Max",
    "previous_names": null
  },
  "location": {
    "home": {
      "city": "München"
    }
  },
  "bio": "Max Mustermann ist Mitgründer und Geschäftsführer der Beispielwerk Analytics GmbH...",
  "expertise": [
    "Produktentwicklung",
    "Softwareentwicklung",
    "Datenanalyse",
    "KI"
  ],
  "contact": {
    "emails": [
      {
        "address": "[email protected]",
        "type": "organization",
        "label": "Allgemeine Kontakt-E-Mail"
      }
    ],
    "phones": []
  },
  "profiles": {
    "linkedin": "https://linkedin.com/in/max-mustermann",
    "github": "https://github.com/max-mustermann",
    "other": []
  },
  "affiliations": [
    {
      "organization": "Beispielwerk Analytics GmbH",
      "relation": "Geschäftsführer"
    }
  ],
  "handelsregister_roles": [
    {
      "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
      "name": "Beispielwerk Analytics GmbH",
      "label": "MANAGING_DIRECTOR",
      "role": {
        "en": "Managing Director",
        "de": "Geschäftsführer"
      },
      "start_date": "2019-06-03",
      "end_date": null
    }
  ],
  "shareholdings": {
    "holdings": {
      "current": [
        {
          "organization": {
            "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
            "name": "Beispielwerk Analytics GmbH",
            "status": "ACTIVE",
            "legal_form": "GmbH",
            "address": {
              "house_number": "12",
              "street": "Beispielstraße",
              "postal_code": "80331",
              "city": "München",
              "county": "München (Stadt)",
              "state": "Bayern",
              "country": "DEU",
              "coordinates": {
                "latitude": 48.13743,
                "longitude": 11.57549
              }
            },
            "registration": {
              "court": "München",
              "register_type": "HRB",
              "register_number": "254891"
            }
          },
          "ownership": {
            "percentage": 25.0,
            "contribution": {
              "amount": 12500,
              "currency": "EUR"
            }
          },
          "as_of": "2025-03-15"
        }
      ]
    },
    "summary": {
      "total_current": 1
    }
  },
  "meta": {
    "request_credit_cost": 20,
    "credits_remaining": 9996743
  }
}

Grundlegende Personendaten

Immer enthalten: entity_id, name, birth_date, name_parts, location, bio, expertise, contact, profiles, handelsregister_roles, affiliations

GET

/v1/search-organizations

1クレジット • 60回/分

高度なフィルタリングとページネーションサポートを備えたドイツ企業の検索。

パラメータ

名前 タイプ 必須 説明
api_key string 条件付き* あなたのAPIキー。x-api-keyヘッダーまたはBearerトークンを使用していない場合は必須
q string 必須 検索クエリ（最小：2文字）
skip integer オプション スキップする結果数（デフォルト：0）
limit integer オプション ページあたりの結果数（デフォルト：10、最大：100）
filters object オプション postal_codeのみでフィルタリング。形式：

Filter

Alle Filter-Schlüssel sind optional. Bereichsfilter akzeptieren {"gte": min, "lte": max} – jede Grenze kann weggelassen werden.

Beispiel-URL 
GET /v1/search-organizations?q=GmbH&limit=10&filters={"postal_code":"80331","legal_form_code":"GmbH","pl_revenue":{"gte":1000000,"lte":5000000}}

Zur besseren Lesbarkeit nicht URL-kodiert – in echten Requests muss der filters-Wert URL-kodiert werden.

Identität & Registrierung
6
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 / array
Deutscher Rechtsformcode, z. B. GmbH, AG, e.V., UG. Einzelner String oder Array.
industry_code string / array
NACE/WZ-Branchencode. Einzelner String oder Array.
industry_scheme string
Klassifikationsschema zu industry_code. Standard: WZ2025.
active boolean
true = nur aktive Unternehmen, false = nur inaktive. Weglassen für beide.
Standort
5
postal_code string
Deutsche 5-stellige Postleitzahl (PLZ).
city string
Stadtname.
state string
Deutsches Bundesland (z. B. Bayern, Hessen).
location_coordinates coordinates
WGS84-Dezimalkoordinaten als Mittelpunkt für die Geo-Suche.
location_max_distance_km number
Radius in km (1–100). Erfordert location_coordinates.
Gericht & Register
3
registration_type string / array
Registertyp: HRA, HRB, GnR, PR oder VR. Einzelner String oder Array.
registration_authority_name string
Name des Gerichts/Registergerichts (z. B. München).
registration_number string
Registernummer (z. B. HRB 12345).
Größe & Mitarbeiter
2
company_size_category enum
Größenklasse: micro, small, medium oder large.
emp_count range
Mitarbeiterzahl-Bereich.
Bilanz
7
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
3
pl_revenue EUR range
Jahresumsatz, in EUR.
pl_net_income EUR range
Jahresüberschuss, in EUR.
pl_ebit EUR range
EBIT / Betriebsergebnis, in EUR.

リクエスト例

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'

レスポンス例

{
  "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クレジット • 5回/分

ドイツ商業登記から公式PDF文書をダウンロードします。

パラメータ

名前 タイプ 必須 説明
api_key string 条件付き* あなたのAPIキー。x-api-keyヘッダーまたはBearerトークンを使用していない場合は必須
company_id string 必須 検索結果からの一意の企業エンティティID
document_type string 必須 文書タイプ。値： shareholders_list, articles_of_association, AD, CD, SI

リクエスト例

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

レスポンス

成功 (200): PDFファイルを直接返します

Content-Type: application/pdf · application/xml (application/pdf für AD, CD, shareholders_list, articles_of_association — application/xml für SI.)

エラー: エラーの詳細を含むJSONを返します

文書タイプ

shareholders_list

株主登録簿文書

articles_of_association

Gesellschaftervertrag / Satzung / Statut Dokument

AD

現在の抜粋（Aktuelle Daten）

CD

履歴抜粋（Chronologische Daten）

SI

Strukturierte Inhalte – als XML-Datei zurückgegeben.

エラー処理

200 OK

リクエスト成功

400 不正なリクエスト

無効なパラメータ

401 認証されていません

無効または欠如しているAPIキー

402 支払いが必要

クレジット不足

429 リクエストが多すぎます

レート制限を超過

500 サーバーエラー

内部サーバーエラー

エラーレスポンス形式

{
  "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 License
インストール 
pip install handelsregister

基本的な使用法

from handelsregister import Handelsregister

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

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

オブジェクトインターフェース

from handelsregister import Company

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

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

データエンリッチメント

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

npm SDK

npm GitHub v0.1.0 • Node.js 14+ • MIT Lizenz
Installation 
npm install handelsregister

Grundlegende Nutzung

const { Handelsregister, Company } = require('handelsregister');

const client = new Handelsregister('your-api-key');
const companyData = await client.fetchOrganization('OroraTech GmbH');

console.log(companyData.name);
console.log(companyData.registration);

TypeScript Unterstützung

import { Handelsregister, Company, CompanyData } from 'handelsregister';

const client = new Handelsregister(process.env.API_KEY);

const company: CompanyData = await client.fetchOrganization({
    q: 'Konux GmbH',
    features: ['financial_kpi', 'related_persons']
});

Async/Await Interface

// Using async/await
async function getCompanyInfo() {
    try {
        const company = await client.fetchOrganization('OroraTech GmbH');
        return company;
    } catch (error) {
        console.error('Error fetching company:', error.message);
    }
}

// Multiple companies
const companies = ['OroraTech GmbH', 'Konux GmbH', 'Celonis SE'];
const results = await Promise.all(
    companies.map(name => client.fetchOrganization(name))
);

Datenanreicherung

await client.enrich({
    filePath: 'companies.csv',
    queryProperties: { name: 'company_name', location: 'city' },
    features: ['financial_kpi', 'related_persons'],
    outputFormat: 'json'
});

MCP Server Beta

Universeller MCP (Model Context Protocol) Server für nahtlose Integration mit KI-Agenten und Workflow-Automatisierung.

Server URL
https://mcp.handelsregister.ai/mcp

Kompatibilität & Integration

Unser MCP Server ist mit jedem MCP-kompatiblen Client verwendbar und ermöglicht die einfache Integration von Handelsregister-Daten in Ihre KI-gestützten Workflows.

Hauptfunktionen

  • Universelle Kompatibilität mit allen MCP Clients
  • Echtzeit-Zugriff auf deutsche Unternehmensdaten
  • Perfekt für agentenbasierte Workflows
  • Native Integration mit OpenAI SDK

Verwendung mit OpenAI Python SDK

Der MCP Server kann direkt mit dem OpenAI Python SDK verwendet werden, um Handelsregister-Daten in Ihre KI-Anwendungen zu integrieren:

Python 
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.responses.create(
    model="gpt-5",
    input="Gib mir die aktuellsten Finanzdaten der Konux GmbH aus München und gebe diese als Markdown-Tabelle aus.",
    tools=[
        {
            "type": "mcp",
            "server_label": "handelsregister",
            "server_url": "https://mcp.handelsregister.ai/mcp",
            "require_approval": "never",
            "headers": {
                "X-API-Key": os.environ["HANDELSREGISTER_API_KEY"]
            },
        }
    ],
)

print(resp.output_text)

Authentifizierung

Die Authentifizierung erfolgt über Ihren handelsregister.ai API-Schlüssel, der als Header übermittelt wird:

X-API-Key: YOUR_API_KEY

Verwenden Sie denselben API-Schlüssel wie für die REST API.

Agentenbasierte Workflows

Der MCP Server ermöglicht die nahtlose Integration von Handelsregister-Daten in komplexe agentenbasierte Workflows:

  • • Automatische Datenextraktion und -analyse
  • • Multi-Agenten-Systeme mit Zugriff auf Unternehmensdaten
  • • Workflow-Automatisierung mit Echtzeit-Datenabruf
  • • Integration in bestehende KI-Pipelines

Credits & Preise

MCP-Anfragen verbrauchen dieselben Credits wie direkte API-Aufrufe, basierend auf den angeforderten Features. Die Preise entsprechen exakt den Preisen der Standard-REST-API.

Anforderungen

  • Gültiger handelsregister.ai API-Schlüssel
  • MCP-kompatibler Client (z.B. OpenAI SDK)
  • Python 3.8+ (für OpenAI SDK)

Wichtige Hinweise

  • • Diese Funktion befindet sich derzeit in der Beta-Phase. Funktionalität und API können sich ändern.
  • • Die Credit-Preise entsprechen exakt den Preisen der Standard-REST-API.
  • • Es gelten dieselben Rate Limits wie für die REST API.
  • • Bei Fragen oder Problemen wenden Sie sich bitte an unseren Support.