germany-handelsregister

Node.js CLI and library for the Handelsregister (German commercial register) portal. Query company data without using a web browser.

Inspired by bundesAPI/handelsregister (Python).

Installation

npm install
npx playwright install chromium

Usage

CLI

Run the CLI via npx (recommended) or npm scripts:

# Via npx – no -- needed when passing flags
npx handelsregister search -s "deutsche bahn" -o all
npx handelsregister announcements --json

# Via npm scripts (-- passes following args to the script)
npm run search -- -s "deutsche bahn" -o all
npm run announcements

# After global install: npm install -g .
handelsregister search -s "deutsche bahn" -o all
handelsregister announcements

Company search examples:

npx handelsregister search -s "deutsche bahn" -o all
npx handelsregister search -s "Gasag AG" -o exact --json

Search options:

| Option | Description | |--------|-------------| | -s, --schlagwoerter <keywords> | Search keywords (required) | | -o, --schlagwort-optionen <option> | all (contain all keywords), min (at least one), exact (exact company name). Default: all | | --json | Output results as JSON | | -d, --debug | Enable debug logging |

Registerbekanntmachungen (announcements)

Search register announcements – newly published changes including new company registrations, transformations, deletions, etc. Covers the last 8 weeks per § 10 HGB.

npx handelsregister announcements                      # last 7 days, all Germany
npx handelsregister announcements --from 01.02.2026 --to 15.02.2026
npx handelsregister announcements --bundesland BE      # Berlin only
npx handelsregister announcements --kategorie 3        # Einreichung neuer Dokumente
npx handelsregister announcements --json

# Enrich with full company data (register_num, status, documents, history)
npx handelsregister announcements --enrich             # slow: ~65s between each company lookup

Announcements options:

| Option | Description | |--------|-------------| | --from <date> | Start date (dd.MM.yyyy). Default: 7 days ago | | --to <date> | End date (dd.MM.yyyy). Default: today | | --bundesland <code> | BW, BY, BE, BR, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH. Default: all | | --kategorie <id> | 1=Löschungsankündigung, 2=Umwandlungsgesetz, 3=Einreichung neuer Dokumente, 4=Sonstige | | --enrich | Fetch full company data for each announcement (slow, respects 60/hr rate limit) | | --json | Output as JSON |

Programmatic Use

Company search:

import { HandelsregisterClient, parseSearchResults } from 'germany-handelsregister';

const client = new HandelsregisterClient({ debug: false });
await client.openStartpage();

const companies = await client.search({
  schlagwoerter: 'deutsche bahn',
  schlagwortOptionen: 'all',
});

await client.close();
console.log(companies);

Register announcements:

import { HandelsregisterClient, parseAnnouncements } from 'germany-handelsregister';

const client = new HandelsregisterClient();
await client.openStartpage();

const announcements = await client.searchAnnouncements({
  dateFrom: '01.02.2026',
  dateTo: '15.02.2026',
  bundesland: '',  // all states
  kategorie: '',   // all categories
  enrich: true,    // add full company data (register_num, status, documents, history)
});

await client.close();
// Each announcement has: date, category, court, name, location, company (if enrich: true)
console.log(announcements);

Rate Limit

The Handelsregister portal enforces a limit of 60 requests per hour per the Nutzungsordnung. Stay within this limit to avoid blocking.

Troubleshooting

• Timeout: The portal can be slow to load. The initial request uses a 60s timeout.
• Form errors: The site structure may change. If searches fail, check for updates to this package.

Requirements

• Node.js 18+
• Playwright Chromium (installed via npx playwright install chromium)

Development

npm test

License

MIT