# German Insolvency Announcements Scraper (`rafiso/german-insolvency-announcements-scraper`) Actor

Unofficial scraper for public German insolvency announcements from the federal and state justice portal. Filter by federal state, publication type, and date, then export normalized records through an Apify dataset.

- **URL**: https://apify.com/rafiso/german-insolvency-announcements-scraper.md
- **Developed by:** [Raso sol](https://apify.com/rafiso) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## German Insolvency Announcements Scraper

An unofficial Apify Actor that extracts public insolvency announcements from the German federal and state justice portal at [neu.insolvenzbekanntmachungen.de](https://neu.insolvenzbekanntmachungen.de/ap/suche.jsf).

The Actor uses Playwright for the portal's stateful Jakarta Faces workflow, BeautifulSoup for deterministic result parsing, Apify Dataset for records, Key-value Store for `RUN_SUMMARY`, and one sticky Apify Proxy session per browser context.

### Important use notice

The source can publish information about natural persons as well as companies. Use the Actor only for a lawful purpose, minimize retention, restrict access, and comply with the source portal's terms and applicable data-protection law. This project is not affiliated with or endorsed by the German justice authorities.

The portal states that result sessions expire after 60 minutes and that direct linking to search results is not permitted. Dataset records therefore expose only the official search-page URL, never session-bound popup URLs.

### Input

| Field | Default | Purpose |
| --- | --- | --- |
| `federalState` | `BW` | Source federal-state code, or `NO_CODE` for all states |
| `announcementType` | `SICHMASS` | Source publication-type code |
| `dateFrom` | 14 days before `dateTo` | First publication date, `YYYY-MM-DD` |
| `dateTo` | Today in Europe/Berlin | Last publication date, `YYYY-MM-DD` |
| `includeDetailText` | `true` | Open publication popups and extract their text |
| `maxItems` | `50` | Unique-record limit, maximum 1,000 |
| `maxPages` | `20` | Result-page safety limit |
| `requestDelayMs` | `1000` | Polite delay with small jitter |
| `navigationTimeoutSecs` | `30` | Browser navigation and result timeout |
| `maxRetries` | `5` | Clean browser/proxy sessions after temporary failures |
| `proxyConfiguration` | Apify Proxy enabled | Integrated Apify Proxy configuration |

Apify Proxy is required. The Actor rejects disabled proxy configuration and custom proxy URLs. It never logs proxy URLs or credentials.

Example input:

```json
{
  "federalState": "BW",
  "announcementType": "SICHMASS",
  "dateFrom": "2026-08-13",
  "dateTo": "2026-08-27",
  "includeDetailText": true,
  "maxItems": 50,
  "proxyConfiguration": {"useApifyProxy": true}
}
```

### Output

Records are pushed to the default dataset as soon as each result page has been parsed. They contain normalized dates, case and court data, debtor/company information, parsed register fields, optional publication text, a deterministic `recordId`, and an extraction timestamp.

`RUN_SUMMARY` contains counts, timings, the sanitized effective input, retry and proxy-session counts, up to 20 typed errors, and `isPartial`.

Failure semantics:

- A run that cannot obtain its first valid result page fails.
- A query exceeding the source portal's 1,000-result cap fails immediately with
  `queryTooBroad` and instructions to narrow its filters.
- Temporary browser, portal, or proxy problems create a clean context with a new sticky proxy session.
- Detail-document failures preserve the base result with `detailText: null`.
- An exhausted later-page failure preserves already stored records and succeeds with `isPartial: true`.
- Repeated pages and duplicate records are detected.

### Local development

Requirements: Python 3.12, Node.js 22, Apify CLI, and an Apify account with Proxy access.

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --require-hashes -r requirements-dev.lock
playwright install chromium
apify login
apify run --purge
```

Run the focused checks:

```bash
python -m ruff check .
python -m pytest
python -m compileall -q src
apify validate-schema
docker build --platform linux/amd64 -t german-insolvency-announcements-scraper:local .
```

The current Apify Playwright image is published for Linux AMD64. The explicit
platform flag is required when building it on an Apple Silicon Mac. Local use of
Apify Proxy also requires the Proxy external-access feature on the Apify account;
cloud Actor runs use the platform's internal Proxy access.

`requirements.lock` and `requirements-dev.lock` are fully resolved with package
hashes. Regenerate them from the short direct-dependency files with `uv pip
compile --python-version 3.12 --generate-hashes` when intentionally upgrading.

### GitHub deployment

Pull requests run `.github/workflows/ci.yml`. Pushes to `main` validate the
project, deploy the `beta` Apify build tag, and run a one-record cloud smoke test
against the exact build number. Production `latest` deployment requires a
manual workflow run with `release_latest=true`, a successful beta smoke test,
and approval through the `apify-production` GitHub environment.

Configure:

- Repository secret `APIFY_TOKEN`.
- Repository variable `APIFY_ACTOR_ID`.
- Protected environment `apify-production` with required reviewers.

Missing deployment configuration fails with an explicit message instead of
silently skipping the deployment job.

### Source limitations

The portal documents a 1,000-result cap for broad searches. Older consumer-insolvency records can require additional identifying search parameters, so broad historical searches may not contain every natural-person proceeding. The Actor reports what the source returns and does not attempt to bypass these rules.

# Actor input Schema

## `federalState` (type: `string`):

Select one German federal state or search all states.

## `announcementType` (type: `string`):

The source portal calls this Gegenstand der Veröffentlichung.

## `dateFrom` (type: `string`):

First publication date in YYYY-MM-DD format. Leave empty in JSON input to use 14 days before dateTo.

## `dateTo` (type: `string`):

Last publication date in YYYY-MM-DD format. Leave empty in JSON input to use today's date in Europe/Berlin.

## `includeDetailText` (type: `boolean`):

Open each result document and include its full publication text. Disabling this makes runs faster.

## `maxItems` (type: `integer`):

Stop after this many unique records. The source itself caps broad searches at 1,000 results.

## `maxPages` (type: `integer`):

Safety cap for result-page pagination.

## `requestDelayMs` (type: `integer`):

Base delay between source interactions. A small random jitter is added automatically.

## `navigationTimeoutSecs` (type: `integer`):

Maximum time to wait for portal navigation or results.

## `maxRetries` (type: `integer`):

Maximum clean browser contexts used after temporary portal or proxy failures.

## `proxyConfiguration` (type: `object`):

Apify Proxy is required. One sticky proxy session is kept for each stateful browser context.

## Actor input object example

```json
{
  "federalState": "BW",
  "announcementType": "SICHMASS",
  "includeDetailText": true,
  "maxItems": 50,
  "maxPages": 20,
  "requestDelayMs": 1000,
  "navigationTimeoutSecs": 30,
  "maxRetries": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `announcements` (type: `string`):

Normalized insolvency announcement records in the default dataset.

## `runSummary` (type: `string`):

Counts, completion state, proxy-session rotations, and sanitized typed errors.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("rafiso/german-insolvency-announcements-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "proxyConfiguration": { "useApifyProxy": True } }

# Run the Actor and wait for it to finish
run = client.actor("rafiso/german-insolvency-announcements-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call rafiso/german-insolvency-announcements-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rafiso/german-insolvency-announcements-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/T1TuTUYWykoUja4Qk/builds/IMXfOwFsQsbGK4mEM/openapi.json