{ "openapi": "3.0.1", "info": { "title": "Herold At $0.8πŸ’° URL Search | Keyword Filters | Enriched Output", "description": "From $0.8/1K. Scrape company listings from herold.at, into a clean, structured dataset. Pull names, full addresses, GPS coordinates, telephone numbers, emails, websites, ratings, reviews, opening hours, payment methods, and founding dates, for any category in any Austrian city or region.", "version": "1.8", "x-build-id": "hAMfxHG4loOIAoQlF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~herold-at-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-herold-at-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/abotapi~herold-at-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-herold-at-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/abotapi~herold-at-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-herold-at-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "1. Search mode", "enum": [ "search", "url" ], "type": "string", "description": "Search mode = pick categories + locations + filters below. URL mode = paste any herold.at URL refined in a browser (recommended for filters not exposed below).", "default": "search" }, "categories": { "title": "Category slugs", "type": "array", "description": "Category URL slugs as they appear on herold.at, e.g. \"restaurant\", \"elektriker\", \"installateur\", \"frisΓΆr\", \"zahnarzt\", \"rechtsanwalt\". Open https://herold.at/gelbe-seiten/ β†’ click any category β†’ copy the slug from the URL path. The cartesian product of categories Γ— locations is searched.", "items": { "type": "string" } }, "locations": { "title": "Location slugs (optional)", "type": "array", "description": "Austrian city/region URL slugs (verified working combos: \"wien\", \"salzburg\", \"bregenz\"). Note: herold.at only generates SEO pages for some city Γ— category combinations; cities like graz, linz, innsbruck, klagenfurt return 404 on the combined URL even though they appear in result addresses. Leave empty to search Austria-wide for each category, which always works. Open a herold.at SERP and copy the location segment from the URL path to verify before running large jobs.", "items": { "type": "string" } }, "urls": { "title": "Search URLs (URL mode)", "type": "array", "description": "One or more full herold.at URLs. Tip: open herold.at in your browser, navigate to a category (e.g. /gelbe-seiten/wien/restaurant/), then paste the resulting URL here. Multi-URL supported. Category slugs and Location slugs above are ignored, they only build a Search-mode URL. The post-fetch filters below (Verified/Rated/Minimum rating) still apply to whatever this URL returns. Pagination starts at the page in the URL and walks forward.", "items": { "type": "string" } }, "verifiedOnly": { "title": "Verified businesses only (post-filter)", "type": "boolean", "description": "Keep only listings flagged \"Verifiziert\" on herold.at. Applied after fetch as a client-side filter (the site does not expose a server-side URL filter for this), so it narrows whichever mode above fetched the listings.", "default": false }, "ratedOnly": { "title": "Rated businesses only (post-filter)", "type": "boolean", "description": "Keep only listings that have at least one rating. Applied after fetch as a client-side filter, so it narrows whichever mode above fetched the listings.", "default": false }, "minRating": { "title": "Minimum average rating (post-filter)", "minimum": 0, "maximum": 5, "type": "integer", "description": "Drop listings with an average rating below this value (1-5). Listings without a rating are also dropped. Applied after fetch as a client-side filter, so it narrows whichever mode above fetched the listings." }, "maxPages": { "title": "Max pages per search", "minimum": 0, "type": "integer", "description": "How many SERP pages to walk per category/location combination (or per pasted URL). Each page returns up to ~30 listings. Leave empty to walk every result page β€” the walk stops naturally once a page repeats listings already collected or herold.at signals no more pages, or sooner once Max listings is reached." }, "maxListings": { "title": "Max listings (total)", "minimum": 0, "type": "integer", "description": "Stop after this many listings across all searches. Defaults to 20 so a run stays small unless you raise it. 0 = unlimited (still bounded by Max pages).", "default": 20 }, "fetchDetails": { "title": "Fetch detail pages (richer data, slower)", "type": "boolean", "description": "When ON, also fetch each listing's detail page for GPS coordinates, opening hours, payment methods, founding date, full review list, description, and breadcrumb. SERP cards already carry name, full street address, postal code, city, region, telephone, email, website, rating, and verified status, so most use cases work fine with this OFF. Multiplies request count ~30Γ— per SERP page when ON. Default OFF.", "default": false }, "resumeFromRunId": { "title": "Resume from a previous run (optional)", "type": "string", "description": "Paste a previous run ID or dataset ID to continue a full-catalogue walk across separate runs. Listings already collected there (matched by listing id) are skipped, so this run only saves the new ones. Leave empty for a normal fresh run. Distinct from Incremental mode below β€” this continues one specific interrupted run, not recurring monitoring." }, "incrementalMode": { "title": "Incremental mode (recurring monitoring)", "type": "boolean", "description": "When ON, this actor remembers the previous run of the SAME search (see State key) and classifies each listing as NEW / UPDATED / UNCHANGED / REAPPEARED / EXPIRED. UNCHANGED and EXPIRED rows are not saved to the dataset unless enabled below β€” this is what keeps a scheduled recurring run cheap. Default OFF (every run returns every listing, as today). Combining with Resume from a previous run above is only safe on the very first incremental run (no baseline yet) β€” once a baseline exists, remove Resume from a previous run or set a different State key.", "default": false }, "stateKey": { "title": "State key (optional, incremental mode only)", "type": "string", "description": "Manually name the incremental baseline for this search, e.g. \"wien-restaurants\". Leave empty to auto-derive one from mode + categories/locations/urls + the post-fetch filters + Fetch detail pages β€” two runs with the exact same search settings then share a baseline automatically. Set this explicitly if you want to run several DIFFERENT search configs against the SAME named baseline, or keep configs that happen to match fully separate." }, "emitUnchanged": { "title": "Include unchanged listings in output (incremental mode only)", "type": "boolean", "description": "When ON, incremental mode also saves listings with no detected change (changeType=\"UNCHANGED\") to the dataset, instead of only NEW/UPDATED/REAPPEARED. This returns β€” and bills for β€” every listing every run, defeating the point of incremental mode for most use cases. Default OFF.", "default": false }, "emitExpired": { "title": "Include expired listings in output (incremental mode only)", "type": "boolean", "description": "When ON, incremental mode also saves a row (changeType=\"EXPIRED\") for each previously-tracked listing that no longer appears, once this run reaches the natural end of the search results (skipped on a capped, resumed, or otherwise incomplete run β€” those cannot tell \"gone\" apart from \"not reached yet\"). This returns β€” and bills for β€” an extra row per disappeared listing. Default OFF.", "default": false }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Herold.at accepts naked Apify residential out of the box. Use country=AT for stable Austrian routing. Datacenter proxies usually work too but may be rate-limited under load." }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify β†’ Settings β†’ Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON β€” the complete record stays in the dataset. Leave empty to skip. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }