# Portál Dražeb Czech Auction Scraper & Monitor (`thescrapelab/portal-drazeb-auction-scraper`) Actor

Scrape, enrich, and monitor public Czech auction listings from Portál Dražeb with prices, dates, locations, documents, images, and change tracking.

- **URL**: https://apify.com/thescrapelab/portal-drazeb-auction-scraper.md
- **Developed by:** [Inus Grobler](https://apify.com/thescrapelab) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 auction 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

## Portál Dražeb Czech Auction Scraper & Monitor

Collect structured public auction intelligence from [Portál Dražeb](https://www.portaldrazeb.cz/). The Actor covers upcoming, in-progress, ended, online, and pre-auction listings, merges duplicate listings across views, exposes public document and image links, and can extract text from selected PDF documents.

> **Unofficial Actor:** This Actor is not affiliated with, endorsed by, or sponsored by Portál Dražeb or its operators.

The output uses English field names while preserving source titles, descriptions, categories, locations, and extracted document text in Czech.

### Quick start

1. Open the Actor in Apify Console and choose the auction status and results limit.
2. Open **Optional filters** only when you need to narrow results by category, county, date, or price.
3. Open **PDF documents** to request PDF text, or keep the default links-only mode for the fastest run.
4. Run the Actor and download the default dataset as JSON, CSV, Excel, XML, or another supported format.

For recurring comparisons, open **Monitoring**, choose `newOnly` or `newAndChanged`, and reuse the same `monitoringKey` with the same filters.

### Pricing

This Actor uses transparent pay-per-event pricing:

- **Actor start:** $0.001 per run, charged automatically by Apify.
- **Auction result:** $0.002 for each emitted `auction` row.
- **Included:** supporting `document` rows, public document links, and requested PDF text extraction do not create additional events.

For example, a run that emits 25 auctions costs $0.051. A monitoring run with no new or changed auctions costs only the $0.001 Actor start event. Platform usage is not added as a separate customer charge. The minimum selectable maximum charge is $0.003 per run, enough for the Actor start and one auction result.

If the run reaches your maximum total charge, it saves the affordable auction results, omits their unmatched document rows, finishes with `status: "partial"`, and reports the withheld count in `OUTPUT.billing`. Withheld auctions are not committed as delivered monitoring results, so a later run with a higher limit can return them.

### What you get

Each run writes two typed row kinds to the default dataset:

- `auction` — status, schedule, prices, calculated appraisal discount, category, location, public auctioneer contact details, images, document links, document metadata hash, and monitoring metadata.
- `document` — document metadata linked by `auctionId`, plus optional Czech PDF text and a typed extraction status.

Missing, blank, or invalid numeric source values stay `null`; a valid numeric zero stays `0`. This prevents absent prices, coordinates, or dimensions from being reported as real zero values.

Sensitive nested source fields such as bidder data, responsible-person records, deposit bank accounts, and payment symbols are not included. Free text is redacted for common bank account, IBAN, Czech personal-number, email, and phone patterns.

### Input

The Console keeps the two essential settings at the top and places less common controls in collapsible sections. API clients can continue using every field listed below; field names, accepted values, and defaults are unchanged.

#### Essential settings

| Field | Default | Description |
| --- | --- | --- |
| `sourceViews` | `["upcoming"]` | One or more of `upcoming`, `inProgress`, `ended`, `online`, and `preAuction`. |
| `maxAuctions` | `1` | Maximum unique auctions, from 1 to 1,000. |

#### Optional filters

| Field | Default | Description |
| --- | --- | --- |
| `categories` | `[]` | Optional English category keys, such as `familyHouse`, `apartment`, or `autoMoto`. |
| `itemCounties` | `[]` | Optional Czech county names for asset locations, such as `Mladá Boleslav`. |
| `auctioneerCounties` | `[]` | Optional Czech county names for auction locations. |
| `startDateFrom`, `startDateTo` | — | Optional ISO 8601 auction-start bounds. |
| `minPriceCzk`, `maxPriceCzk` | — | Optional source item-price bounds in CZK. |
| `sortOrder` | `startAsc` | `startAsc` or `startDesc`. |

#### PDF documents

| Field | Default | Description |
| --- | --- | --- |
| `documentMode` | `links` | `links` returns metadata and URLs; `text` also extracts selected PDFs. |
| `maxPdfDocumentsPerAuction` | `2` | PDF extraction cap per auction, up to 5. |
| `maxPdfDocumentsTotal` | `10` | Global PDF extraction cap per run, up to 100. |

#### Monitoring

| Field | Default | Description |
| --- | --- | --- |
| `outputMode` | `all` | `all`, `newOnly`, or `newAndChanged`. |
| `monitoringKey` | query fingerprint | Optional stable name for a repeat monitoring stream. |

#### Example input

```json
{
  "sourceViews": ["upcoming", "online"],
  "categories": ["familyHouse", "apartment"],
  "maxAuctions": 25,
  "documentMode": "links",
  "outputMode": "newAndChanged",
  "monitoringKey": "prague-residential"
}
```

### Output example

```json
[
  {
    "recordType": "auction",
    "auctionId": "XYqnB",
    "title": "Dražba rodinného domu",
    "sourceStatus": "upcoming",
    "startsAt": "2026-08-31T07:00:00.000Z",
    "appraisedValueCzk": 3021000,
    "startingPriceCzk": 2014000,
    "documentCount": 2,
    "changeType": "new",
    "changedFields": [],
    "sourceUrl": "https://www.portaldrazeb.cz/drazba/example"
  },
  {
    "recordType": "document",
    "auctionId": "XYqnB",
    "documentId": "mea5o",
    "documentType": "auction_decree",
    "extractionStatus": "notRequested",
    "url": "https://www.portaldrazeb.cz/upload/auction-document/mea5o"
  }
]
```

### Monitoring behavior

The Actor compares stable groups for status, schedule, pricing, content, documents, images, location, and auctioneer details. Auction rows receive:

- `changeType`: `new`, `changed`, `unchanged`, or `unknown`
- `changedFields`: changed field groups
- `contentHash`, `firstSeenAt`, and `lastSeenAt`

After a fingerprint upgrade, an existing stream may emit a one-time `fingerprintVersion` change to make the state migration explicit.

Use the same `monitoringKey` and filters for repeat runs. A monitoring key identifies one comparison stream; reusing it with different filters mixes those result sets and is not supported.

Only one run can hold a stream's renewable lease at a time. `newOnly` and `newAndChanged` stop with an actionable error if monitoring storage or the lease is unavailable at startup, because change-only output would otherwise be unreliable. In that startup case, `all` still returns current rows, marks their `changeType` as `unknown`, and reports a monitoring warning in the `OUTPUT` summary. If an acquired lease is lost later in the run, every output mode fails without committing monitoring state; treat any dataset attached to that failed run as incomplete.

Entries whose `lastSeenAt` is older than 180 days are removed when state is committed. A later reappearance is therefore classified as `new`. The Actor does not infer removed auctions when a listing disappears from a selected view.

### PDF extraction

In `text` mode, only public source PDFs are downloaded. Auction decrees are selected before expert reports and other documents. Within each group, ordering uses `updatedAt` when present and otherwise `createdAt`; newer timestamps come first and documents with no timestamp come last. Each selected file is limited to 15 MB, extracted text is capped at 200,000 characters, and scanned image-only PDFs are not OCRed. Parsing runs in an isolated worker with a hard 30-second limit per document.

The Actor keeps a 45-second finalization reserve before the run timeout so it can save the dataset and `OUTPUT` summary. If a parser reaches that reserve, its worker is terminated before the collected results are finalized. The document `extractionStatus` values are:

- `notRequested` — links-only mode; no text extraction was requested.
- `notSelected` — an eligible PDF was outside the configured per-auction or per-run cap.
- `unsupported` — the document was not identified as a PDF.
- `tooLarge` — the declared or downloaded file exceeded 15 MB.
- `timeBudgetExceeded` — extraction stopped to preserve finalization time; remaining rows were still saved.
- `extracted` — text was extracted and redacted successfully.
- `emptyText` — the PDF parser returned no text, commonly for scanned image-only files.
- `failed` — download or parsing failed, including a PDF that exceeded the 30-second parser safety limit; see `extractionError`.

A run with one or more `timeBudgetExceeded` documents finishes with `status: "partial"` in its summary rather than losing the collected auction and document rows. The default cloud memory is 256 MB; lowering it can make PDF parsing unreliable.

### Run summary

The `OUTPUT` key-value-store record contains:

- `status` — `succeeded` or `partial`.
- `startedWith` — the main input choices used by the run.
- `counts` — fetched, normalized, emitted, change-classification, and PDF-extraction totals.
- `source` — successful and failed source views with per-view counts.
- `monitoring` — availability, namespace, state key, warning details, and the number of stale entries pruned.
- `billing` — pricing model, event name, unit price, candidate/charged auction counts, and charge-limit status.
- `warnings` — partial-view, monitoring fallback, normalization, or PDF time-budget notices.
- `storage` and `finishedAt` — output identifiers and completion time.

`partial` means usable output was saved with at least one warning; inspect `warnings` and the relevant count group before consuming the result.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('thescrapelab/portal-drazeb-auction-scraper').call({
    sourceViews: ['upcoming'],
    maxAuctions: 10,
    documentMode: 'links',
    outputMode: 'all',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const row of items) console.log(row.recordType, row.auctionId);
```

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("thescrapelab/portal-drazeb-auction-scraper").call(
    run_input={
        "sourceViews": ["upcoming"],
        "maxAuctions": 10,
        "documentMode": "links",
        "outputMode": "all",
    }
)

for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["recordType"], row["auctionId"])
```

### Important limitations

- This Actor uses public website routes and is not an official Portál Dražeb API integration.
- Source fields and availability can change; partial-view failures are reported in the `OUTPUT` summary.
- Extracted text can contain source errors and should be checked against the linked original document.
- PDF text extraction is sequential and bounded for predictable source load; large extraction selections take longer than links-only runs.
- Auction data is informational. Verify deadlines, prices, eligibility, and legal details on the original listing before acting.
- Use the data lawfully and respect privacy, contractual, and regulatory obligations applicable to your use case.

### Support

If a source field changes, a run fails, or an output value looks incorrect, open an issue on the Actor's [Apify support tab](https://apify.com/thescrapelab/portal-drazeb-auction-scraper/issues). Include the run ID, sanitized input, expected behavior, and the relevant `OUTPUT.warnings` entry. Do not include Apify tokens or private credentials.

# Actor input Schema

## `sourceViews` (type: `array`):

Choose one or more public listing states. Auctions found in several states are returned only once.

## `maxAuctions` (type: `integer`):

Maximum unique auctions to return across all selected statuses. Higher limits can increase run time and result charges.

## `categories` (type: `array`):

Optional asset categories. Leave empty to include every category.

## `itemCounties` (type: `array`):

Optional Czech county names for the auctioned asset location, for example Mladá Boleslav. Names are passed to the public source filter.

## `auctioneerCounties` (type: `array`):

Optional Czech county names for where the auction is held.

## `startDateFrom` (type: `string`):

Optional ISO 8601 date or date-time lower bound for auction start time.

## `startDateTo` (type: `string`):

Optional ISO 8601 date or date-time upper bound for auction start time.

## `minPriceCzk` (type: `integer`):

Optional minimum source item price in Czech koruna.

## `maxPriceCzk` (type: `integer`):

Optional maximum source item price in Czech koruna.

## `sortOrder` (type: `string`):

Choose whether earlier or later auction start times appear first.

## `documentMode` (type: `string`):

Choose whether to return public document links or also extract Czech text from selected PDF files.

## `maxPdfDocumentsPerAuction` (type: `integer`):

Maximum PDFs to extract for each auction in text mode. Auction decrees are selected before expert reports and other documents, with newer documents first within each group.

## `maxPdfDocumentsTotal` (type: `integer`):

Global PDF extraction limit for predictable run time and cost.

## `outputMode` (type: `string`):

Return all current auctions, only first-seen auctions, or first-seen and changed auctions. Change-only modes require exclusive access to monitoring state.

## `monitoringKey` (type: `string`):

Optional stable namespace for repeat comparisons. Reuse a key only with the same filters. If omitted, a fingerprint of the filters is used; entries unseen for 180 days expire from comparison state.

## Actor input object example

```json
{
  "sourceViews": [
    "upcoming"
  ],
  "maxAuctions": 1,
  "categories": [],
  "itemCounties": [],
  "auctioneerCounties": [],
  "sortOrder": "startAsc",
  "documentMode": "links",
  "maxPdfDocumentsPerAuction": 2,
  "maxPdfDocumentsTotal": 10,
  "outputMode": "all"
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

Typed auction and document records in the default dataset.

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

Succeeded or partial status, source/change/PDF counts, pay-per-event billing, warnings, monitoring availability and pruning, and output storage identifiers.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thescrapelab/portal-drazeb-auction-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("thescrapelab/portal-drazeb-auction-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 '{}' |
apify call thescrapelab/portal-drazeb-auction-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,thescrapelab/portal-drazeb-auction-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/5xBZExLGuNo2BdKLx/builds/MObbNQsgweZ5LQzSZ/openapi.json