Metadata-Version: 2.4
Name: handelsregister
Version: 0.4.0
Summary: Python SDK für den Zugriff auf die Handelsregister AI API
Home-page: https://github.com/Handelsregister-AI/handelsregister
Author: Handelsregister Team
Author-email: Handelsregister Team <info@handelsregister.ai>
License: MIT
Project-URL: Homepage, https://github.com/Handelsregister-AI/handelsregister
Project-URL: Bug Reports, https://github.com/Handelsregister-AI/handelsregister/issues
Keywords: handelsregister,api,german company data,business data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.23.0
Requires-Dist: tqdm>=4.0.0
Requires-Dist: pandas>=1.0.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 🔍 Handelsregister Python SDK

[![PyPI version](https://img.shields.io/pypi/v/handelsregister.svg)](https://pypi.org/project/handelsregister/)
[![Python Versions](https://img.shields.io/pypi/pyversions/handelsregister.svg)](https://pypi.org/project/handelsregister/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A modern Python client for the [Handelsregister.ai](https://handelsregister.ai) API. Structured, reliable, and fast access to the German commercial register (Handelsregister): company master data, financials, management, shareholders, UBOs, person profiles, and official PDF documents.

## ✨ Features

- 🔎 **Company lookup** — `fetch-organization` with configurable feature flags
- 👤 **Person profiles** — `fetch-person` (Handelsregister roles + web data)
- 🗂️ **Search** — paginated `search-organizations` with postal-code filter
- 📊 **Financial data** — KPIs, balance sheet, P&L, full annual reports (MD/HTML)
- 👥 **Management** — current and past related persons with roles
- 🤝 **Shareholders, UBOs, shareholdings** — who owns the company, who the company owns
- 📰 **News, publications, insolvency publications**
- 🌐 **Website content** — structured Markdown, optimized for LLMs
- 📄 **Document downloads** — Gesellschafterliste, Gesellschaftsvertrag, AD, CD
- 🔐 **Auth** — `x-api-key` header or Bearer token, plus token management
- 📚 **Batch enrichment** — resilient CSV/JSON/XLSX enrichment with snapshots
- ⚡ **Live mode** — opt-in realtime lookups against the Handelsregister

## 📦 Installation

```bash
pip install handelsregister
```

## 🔑 Authentication

You can authenticate in two ways:

**API key (recommended for server-to-server):**

```bash
export HANDELSREGISTER_API_KEY=your_api_key_here
```

```python
from handelsregister import Handelsregister

client = Handelsregister(api_key="your_api_key_here")
```

**Bearer token (fine-grained control, expiration):**

```bash
export HANDELSREGISTER_BEARER_TOKEN=your_token_here
```

```python
client = Handelsregister(bearer_token="your_token_here")
```

When both are provided, the bearer token wins.

## 🚀 Quick Start

### Company lookup

```python
from handelsregister import Handelsregister

client = Handelsregister()

result = client.fetch_organization(
    q="KONUX GmbH München",
    features=["related_persons", "financial_kpi", "shareholders"],
    ai_search="on-default",          # optional: enable AI search
    # realtime_mode="handelsregister-default",  # +10 credits for live data
)

print(result["name"], result["registration"]["register_number"])
```

### Object-oriented `Company` interface

```python
from handelsregister import Company

company = Company(
    "OroraTech GmbH München",
    features=[
        "related_persons",
        "financial_kpi",
        "balance_sheet_accounts",
        "shareholders",
        "ubos",
        "shareholdings",
        "annual_financial_statements",
        "news",
    ],
)

print(company.name, company.is_active)
print(company.formatted_address)

# Management
for person in company.current_related_persons:
    print(person["name"], "-", person["role"]["en"]["long"])

# Shareholders (who owns the company)
for entry in company.shareholders.entries:
    print(entry.display_name, entry.percentage)

# Ultimate beneficial owners
for ubo in company.ubos.resolved:
    print(ubo.name, ubo.percentage)

# Outbound shareholdings (what the company owns)
for holding in company.shareholdings.current:
    print(holding.organization_name, holding.percentage)

# News
for article in company.news:
    print(article["publication_date"], article["title"])
```

### Person profiles

The `/v1/fetch-person` endpoint merges Handelsregister records with public web data. `ai_search` is always on for this endpoint (the 15-credit base cost includes the AI enrichment). `organization_q` is required to disambiguate common names.

```python
from handelsregister import Person

person = Person(
    person_q="Max Mustermann",
    organization_q="Beispielwerk Analytics GmbH",
    features=["shareholdings"],  # +5 credits, only if data is returned
)

print(person.canonical_name, "-", person.home_city)
print(person.bio)

for role in person.handelsregister_roles:
    print(role["name"], role["label"], role.get("start_date"), role.get("end_date"))

for holding in person.shareholdings.current:
    print(holding.organization_name, holding.percentage, holding.as_of)
```

### Search

```python
client = Handelsregister()

page = client.search_organizations(
    q="tech",
    limit=10,
    skip=0,
    filters={"postal_code": "80992"},
)

print(page["total"])
for item in page["results"]:
    print(item["name"], item["registration"]["register_number"])
```

## 📄 Document Downloads

```python
from handelsregister import Handelsregister, Company

client = Handelsregister()

# Get the company's entity_id
result = client.fetch_organization(q="KONUX GmbH München")
entity_id = result["entity_id"]

# Download documents directly from the client
client.fetch_document(
    company_id=entity_id,
    document_type="shareholders_list",       # Gesellschafterliste
    output_file="konux_shareholders.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="articles_of_association", # Gesellschaftsvertrag / Satzung
    output_file="konux_articles.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="AD",                      # Aktueller Ausdruck
    output_file="konux_current.pdf",
)

pdf_bytes = client.fetch_document(
    company_id=entity_id,
    document_type="CD",                      # Chronologischer Ausdruck
)

# Or via the Company helper
company = Company("OroraTech GmbH München")
company.fetch_document(
    document_type="shareholders_list",
    output_file="ororatech_shareholders.pdf",
)
```

### Available document types

| Document Type              | Description                                        |
|----------------------------|----------------------------------------------------|
| `shareholders_list`        | Gesellschafterliste                                |
| `articles_of_association`  | Gesellschaftsvertrag / Satzung / Statut            |
| `AD`                       | Aktuelle Daten (current excerpt)                   |
| `CD`                       | Chronologische Daten (historical excerpt)          |

## 🔐 Bearer Token Management

If you prefer managing bearer tokens over sharing an API key:

```python
client = Handelsregister(api_key="your_api_key_here")

# Create a new token
created = client.create_token(
    token_name="My Application",
    abilities=["*"],
    expires_at="2026-01-01 00:00:00",
)
print(created)

# List / revoke
tokens = client.list_tokens()
client.revoke_token(token_id=42)
client.revoke_all_tokens()
```

## 📊 Data Enrichment

Enrich a CSV/JSON/XLSX file of companies with Handelsregister data. Intermediate snapshots let you resume long-running jobs.

```python
from handelsregister import Handelsregister

client = Handelsregister()

client.enrich(
    file_path="companies.csv",
    input_type="csv",
    query_properties={
        "name": "company_name",   # map 'company_name' column to query
        "location": "city",       # map 'city' column to query
    },
    snapshot_dir="snapshots",
    params={
        "features": ["related_persons", "financial_kpi", "ubos"],
        "ai_search": "on-default",
    },
    output_format="csv",
)
```

There is also a DataFrame convenience:

```python
import pandas as pd
from handelsregister import Handelsregister

client = Handelsregister()
df = pd.read_csv("companies.csv")
enriched = client.enrich_dataframe(
    df,
    query_properties={"name": "company_name", "location": "city"},
    params={"features": ["financial_kpi"]},
)
```

## 🖥️ Command Line Interface

Installing the package exposes the `handelsregister` CLI. If the optional `rich` dependency is installed, commands render colorful tables.

```bash
# Company lookup (defaults: all standard features + AI search)
$ handelsregister fetch "KONUX GmbH München"

# Raw JSON
$ handelsregister fetch json "KONUX GmbH München"

# Opt-in to realtime mode for live register data
$ handelsregister fetch "KONUX GmbH München" --realtime-mode handelsregister-default

# Person profile
$ handelsregister person \
    --person "Max Mustermann" \
    --organization "Beispielwerk Analytics GmbH" \
    --feature shareholdings

# Search
$ handelsregister search "tech" --postal-code 80992 --limit 20

# Enrich a file
$ handelsregister enrich companies.csv --input csv \
    --query-properties name=company_name location=city \
    --snapshot-dir snapshots \
    --feature related_persons --feature financial_kpi \
    --output-format csv

# Download documents
$ handelsregister document "KONUX GmbH München" \
    --type shareholders_list --output konux_shareholders.pdf

$ handelsregister document "KONUX GmbH München" \
    --type articles_of_association --output konux_articles.pdf
```

## 📋 Available Features (`fetch-organization`)

| Feature Flag                         | Description                                                   |
|--------------------------------------|---------------------------------------------------------------|
| `related_persons`                    | Current and past management                                   |
| `financial_kpi`                      | Yearly revenue, net income, employees, …                      |
| `balance_sheet_accounts`             | Hierarchical balance sheet data                               |
| `profit_and_loss_account`            | Profit & loss statements                                      |
| `annual_financial_statements`        | Full annual reports as Markdown                               |
| `annual_financial_statements__html`  | Full annual reports as HTML                                   |
| `publications`                       | Official Handelsregister publications                         |
| `insolvency_publications`            | Insolvency court publications                                 |
| `news`                               | News articles about the company                               |
| `website_content`                    | Company website as structured Markdown (AI mode, 0 credits)   |
| `shareholders` (beta)                | Shareholders with capital contribution and ratio              |
| `ubos` (beta)                        | Ultimate beneficial owners (resolved / unresolved / coverage) |
| `shareholdings` (beta)               | Outbound shareholdings (what the company owns in others)      |

`realtime_mode="handelsregister-default"` forces a live Handelsregister lookup (+10 credits), independent of the feature flags above.

## 🔍 `Company` properties

```python
# Basic
company.name
company.entity_id
company.status
company.is_active
company.purpose

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

# Contact & address
company.address
company.formatted_address
company.coordinates
company.website
company.phone_number
company.email

# Financial
company.financial_kpi
company.financial_years
company.balance_sheet_accounts
company.profit_and_loss_account
company.annual_financial_statements
company.annual_financial_statements_html
company.get_financial_kpi_for_year(2023)
company.get_balance_sheet_for_year(2023)
company.get_profit_and_loss_for_year(2023)
company.get_annual_financial_statement_for_year(2023)  # Markdown
company.get_annual_financial_statement_for_year(2023, html=True)

# People & ownership
company.current_related_persons
company.past_related_persons
company.get_related_persons_by_role("MANAGING_DIRECTOR")
company.shareholders           # ShareholderInfo
company.ubos                   # UBOInfo
company.shareholdings          # ShareholdingsInfo

# News & publications
company.publications
company.insolvency_publications
company.news
company.website_content
```

## 👤 `Person` properties

```python
person.entity_id
person.name
person.canonical_name
person.given_name
person.family_name
person.previous_names
person.birth_date
person.home_city
person.bio
person.expertise
person.emails
person.phones
person.linkedin
person.github

person.handelsregister_roles
person.current_handelsregister_roles
person.get_handelsregister_roles_by_label("MANAGING_DIRECTOR")
person.affiliations

person.shareholdings           # PersonShareholdings (requires feature flag)
```

## 📜 License

MIT — see [LICENSE](LICENSE).
