# Zoll-Auktion Offer & Deal Finder (`webdesigndetail/zoll-auction-deal-finder`) Actor

Fetch category-based Zoll-Auktion offers, visit every detail page, and rank transparent deal-potential signals.

- **URL**: https://apify.com/webdesigndetail/zoll-auction-deal-finder.md
- **Developed by:** [Webdesign Detail](https://apify.com/webdesigndetail) (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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Zoll-Auktion Offer & Deal Finder

Collect structured public auction offers by category and surface low-competition, ending-soon
opportunities with transparent evidence.

This Actor visits each discovered offer page. It does not log in, place bids, add watchlist entries,
submit any form, use an LLM, or compare prices on eBay or another marketplace.

### Quick start

1. Select one or more top-level categories. You can also paste exact Zoll-Auktion subcategory URLs.
2. Optionally enter a five-digit German postcode and choose a 20, 50, 100, 250, or 500 km radius.
3. Choose `all` to export every processed offer, or `dealsOnly` to retain only offers that meet your
   configured filters and minimum score.
4. Set a practical `maxOffers` limit, then click **Start**.
5. Open the **Dataset** for offer records and inspect the `OUTPUT` record before using the results.

### What you get

Each dataset item includes, when publicly available:

- Auction ID, title, canonical URL, category, and source position.
- Current bid, minimum next bid, currency, bid and view counts.
- Auction start/end timestamps and remaining-time text.
- Seller name, city/state, postcode-search distance, pickup, shipping, payment, VAT, and auction type.
- Normalized description, original image URLs, and linked PDF documents.
- Deal score, label, matched status, positive signals, and risk flags.

The `OUTPUT` key-value-store record reports counts, completeness, proxy mode, timings, and capped
typed errors.

### Finding deals

Set `postalCode` and `radiusKm` to search every selected category around one German postcode. The
Actor first opens the category page, reads its live parent and subcategory selection, submits those
IDs through the site's public GET search format, and then follows the exact filtered next-page URLs.
This avoids maintaining fragile hardcoded subcategory lists.

Use `keywords`, `maxCurrentBidEur`, `maxBidCount`, `endingWithinHours`, and `deliveryMethod` to
describe your opportunity. Choose `dealsOnly` to store only offers satisfying every configured
criterion and `minDealScore`.

The score is deliberately explainable:

- Lower bid competition adds more points.
- Auctions ending within 6, 24, 72, or 168 hours add progressively fewer points.
- Shipping or pickup availability contributes a small convenience signal.
- A bid far below your configured maximum adds a budget signal.
- If the seller explicitly states a `Neupreis`, `Kaufpreis`, `Schätzwert`, `Zeitwert`, `Marktwert`,
  `Wiederbeschaffungswert`, or `Listenpreis`, the Actor can report the nominal difference.
- Defect, parts-only, accident, repair, or unverified-function language reduces the score.

`high`, `promising`, `watch`, and `weak` describe auction opportunity signals—not guaranteed value.
The Actor performs no independent market appraisal. Seller-stated reference values are flagged as
unverified, and pickup/travel costs are not estimated.

### Input example

```json
{
    "categoryIds": ["197", "1130"],
    "postalCode": "77933",
    "radiusKm": 100,
    "maxOffers": 100,
    "keywords": ["Lego", "Werkzeug"],
    "excludeKeywords": ["defekt"],
    "maxCurrentBidEur": 500,
    "maxBidCount": 3,
    "endingWithinHours": 72,
    "deliveryMethod": "any",
    "outputMode": "dealsOnly",
    "minDealScore": 50,
    "proxyConfiguration": {"useApifyProxy": true}
}
```

`categoryUrls` additionally accepts exact HTTPS category and subcategory URLs on
`www.zoll-auktion.de`. Arbitrary hosts and non-category paths are rejected.

### Output example

```json
{
    "auctionId": "977055",
    "title": "Example auction title",
    "url": "https://www.zoll-auktion.de/auktion/produkt/example/977055",
    "detailStatus": "complete",
    "currentBid": 2500.0,
    "currency": "EUR",
    "bidCount": 2,
    "auctionEndAt": "2026-09-10T10:00:00+00:00",
    "shippingAvailable": false,
    "pickupAvailable": true,
    "dealScore": 61,
    "dealLabel": "promising",
    "isDeal": true,
    "dealSignals": ["Low bid competition"],
    "riskFlags": [],
    "analysisScope": "Transparent auction-opportunity signals and seller-stated reference values only; no independent market appraisal."
}
```

The example shows the record shape, not a current auction or guaranteed value. Fields absent from a
source page are omitted rather than guessed.

### Completeness states

- `SUCCEEDED`: all processed pages/details completed.
- `EMPTY`: the run completed but no records remained after the selected output mode.
- `PARTIAL`: valid records were preserved, but at least one category/detail failed.
- `FAILED`: the crawl could not obtain a usable category result.

Detail failures produce a limited card-level fallback item with `detailStatus: "failed"`; such an
item never qualifies as a deal.

### Proxy and load policy

Apify Proxy is mandatory and custom proxy URLs are rejected. Defaults are limited to three concurrent
requests and 30 tasks per minute. The crawler respects robots.txt and follows the site's exact next-page
URL. Raising limits can increase blocking and target load.

### Cost and platform integrations

The estimated run price is shown by Apify before execution and depends on the pricing configured on
the Store listing. A run processes roughly one category request per result page plus one detail request
per discovered auction; postcode searches add an initial category lookup. Keep `maxOffers` and
`maxPagesPerCategory` bounded when testing.

You can run the Actor manually, on a schedule, through the Apify API, or from Apify integrations and
webhooks. The output schema exposes direct links to the default dataset and the `OUTPUT` summary, so
automation should check `status` and `isPartial` before consuming records.

### Limitations

- Auction prices can change after the item was scraped.
- Shipping and pickup details vary; unknown costs are not included in value comparisons.
- Descriptions and condition statements come from sellers and are not verified.
- The page structure may change. Check `OUTPUT.isPartial` and errors before consuming a run.
- The Actor does not provide financial, legal, appraisal, or bidding advice.

### Responsible use and affiliation

Only run or publish this Actor when you have permission and a lawful basis for the intended use.
Review the current Zoll-Auktion robots policy and terms before operating it. Apify Proxy does not
grant permission to scrape or republish content.

This is an unofficial independent Actor. It is not affiliated with, endorsed by, or operated by
Zoll-Auktion, the German customs administration, or any listed seller.

### Support

Use the Actor's **Issues** tab on Apify. Include the run ID, build number, sanitized input, `OUTPUT`
summary, and the first relevant error. Never post your Apify token or private proxy credentials.

# Actor input Schema

## `categoryIds` (type: `array`):

One or more top-level Zoll-Auktion categories.

## `categoryUrls` (type: `array`):

Optional exact Zoll-Auktion category or subcategory URLs.

## `postalCode` (type: `string`):

Optional five-digit German postcode used with the radius filter for every selected category.

## `radiusKm` (type: `integer`):

Radius around postalCode. Use 20, 50, 100, 250, or 500 km. Ignored when postalCode is empty.

## `maxOffers` (type: `integer`):

Maximum number of unique detail pages processed across all categories.

## `maxPagesPerCategory` (type: `integer`):

Safety limit for exact server-provided pagination.

## `keywords` (type: `array`):

Optional title or description terms. An offer matching any term passes this criterion.

## `excludeKeywords` (type: `array`):

Reject offers whose title or description contains any listed term.

## `maxCurrentBidEur` (type: `number`):

Optional EUR budget cap. Uses the minimum next bid where available.

## `maxBidCount` (type: `integer`):

Deal filter for low-competition offers.

## `endingWithinHours` (type: `number`):

Deal filter for auctions ending within this many hours.

## `deliveryMethod` (type: `string`):

Optionally require shipping or pickup availability.

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

Store all offers or only offers meeting every configured deal criterion and minimum score.

## `minDealScore` (type: `integer`):

Minimum transparent opportunity score used by deals-only output.

## `includeDescription` (type: `boolean`):

Include the normalized offer description in each dataset item.

## `includeImages` (type: `boolean`):

Include original image URLs without downloading image files.

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

Apify Proxy is mandatory for all site requests.

## `maxConcurrency` (type: `integer`):

Maximum parallel requests. Keep this low for the public service.

## `maxRequestsPerMinute` (type: `integer`):

Total crawl throughput limit across category and detail requests.

## `maxRequestRetries` (type: `integer`):

Retries for transient network, blocking, and server failures.

## `requestTimeoutSecs` (type: `integer`):

Maximum time allowed for one HTTP navigation.

## Actor input object example

```json
{
  "categoryIds": [
    "197"
  ],
  "categoryUrls": [],
  "radiusKm": 100,
  "maxOffers": 100,
  "maxPagesPerCategory": 10,
  "keywords": [],
  "excludeKeywords": [],
  "maxBidCount": 3,
  "endingWithinHours": 72,
  "deliveryMethod": "any",
  "outputMode": "all",
  "minDealScore": 50,
  "includeDescription": true,
  "includeImages": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 3,
  "maxRequestsPerMinute": 30,
  "maxRequestRetries": 3,
  "requestTimeoutSecs": 60
}
```

# Actor output Schema

## `results` (type: `string`):

Structured and ranked offer records.

## `summary` (type: `string`):

Counts, completeness state, filters, and 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("webdesigndetail/zoll-auction-deal-finder").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("webdesigndetail/zoll-auction-deal-finder").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 webdesigndetail/zoll-auction-deal-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,webdesigndetail/zoll-auction-deal-finder"
        }
    }
}

```

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/Zmg7cH4XMZGf4WzWM/builds/26Cj8iRdSMsdgoszq/openapi.json