# Firmy.cz Crane Scraper (`magistercrane/firmy-cz-crane-scraper`) Actor Scrape company listings and profile details from Firmy.cz by search query and Czech location. Extract names, addresses, phones, emails, websites, ICO, descriptions, categories, GPS coordinates, ratings, and optional ARES establishment dates. - **URL**: https://apify.com/magistercrane/firmy-cz-crane-scraper.md - **Developed by:** [MagisterCrane](https://apify.com/magistercrane) (community) - **Categories:** Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.50 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ### What Does Firmy.cz Scraper Do? Firmy.cz Scraper extracts company listings and company profile details from [Firmy.cz](https://www.firmy.cz/). It is built for lead research, local market mapping, and company data collection in the Czech Republic. The Actor accepts one or more search queries, one or more locations, and returns structured JSON records in the default Apify Dataset. It can also enrich scraped ICO values from ARES to add company establishment dates. ### What This Actor Can Do - Search Firmy.cz by keyword, category, service, or business phrase. - Search the whole Czech Republic, one city, or multiple cities in one run. - Collect company profile URLs, names, addresses, descriptions, categories, contacts, websites, ICO values, data boxes, GPS coordinates, and ratings. - Extract multiple phone numbers with labels and mark the primary phone number. - Optionally open company detail pages for richer contact and profile data. - Optionally enrich companies from ARES and add `established_at`. - Optionally keep only companies whose real locality matches the requested municipality. ### How To Use This Actor 1. Enter a search query such as `logistika`, `malířství`, or `úklidové služby`. 2. Add one or more city names if you are not searching the whole country. 3. Leave the location fields empty to search the whole Czech Republic. 4. Set `maxResultsPerQuery` based on how many companies you want from each query and location. 5. Enable `includeDetails` for richer contact data. 6. Enable `enrichAres` when you need company establishment dates. 7. Run the Actor and download the results from the default Dataset. ### Input You can configure the Actor in Apify Console using the input form, or pass the same values as JSON through the API. #### Example Input ```json { "searchQueries": ["logistika", "autodoprava"], "locations": ["Kladno", "Unhost"], "maxResultsPerQuery": 20, "includeDetails": true, "strictLocationMatch": true, "enrichAres": true, "useApifyProxy": false, "listingSource": "api" } ```` #### Input Fields | Field | Type | Description | | --- | --- | --- | | `searchQuery` | string | Single search query. Use `searchQueries` for multiple queries. Czech characters are supported. | | `searchQueries` | string array | Optional list of search queries to run in one Actor session. When filled, it is used instead of `searchQuery`. | | `location` | string | Single city or municipality name, for example `Kladno`. Leave empty to search the whole Czech Republic. | | `locations` | string array | Optional list of city or municipality names to run in one Actor session. When filled, it is used instead of `location`. | | `maxResultsPerQuery` | integer | Maximum number of companies to collect for each search query and location before deduplication. Default is `20`. | | `maxResults` | integer | Backward-compatible alias for `maxResultsPerQuery`. | | `includeDetails` | boolean | Opens each company profile and enriches the output with detailed fields. Default is `true`. | | `strictLocationMatch` | boolean | Keeps only companies whose real locality matches one of the requested municipalities. | | `enrichAres` | boolean | Looks up scraped ICO values in ARES and adds `established_at` and ARES metadata. | | `maxPages` | integer | Safety limit for listing pagination. Default is `10`. | | `delayMinSeconds` | number | Minimum delay between requests in seconds. | | `delayMaxSeconds` | number | Maximum delay between requests in seconds. | | `useApifyProxy` | boolean | Routes Firmy.cz and ARES requests through Apify Proxy when proxy credentials are available. | | `listingSource` | string | Listing source: `api` uses the Firmy.cz frontend API and falls back to HTML if needed; `html` uses HTML pages. | ### Output The Actor stores one JSON item per company in the default Apify Dataset. The first fields are ordered for quick lead review: ```text search_query name phone_primary email address established_at description profile_url ``` #### Output Fields | Field | Description | | --- | --- | | `search_query` | Search query that produced the record first. | | `name` | Company name from Firmy.cz. | | `phone_primary` | Primary phone number, usually the schema.org phone or the first detected phone. | | `email` | Company email address when available. | | `address` | Full company address. | | `established_at` | Company establishment date from ARES when `enrichAres` is enabled and ICO is available. | | `description` | Company description from listing or detail page. | | `profile_url` | Firmy.cz company profile URL. | | `location` | Requested location that produced the record first. | | `matched_search_queries` | All input queries that matched the same deduplicated company. | | `matched_locations` | All requested locations that matched the same deduplicated company. | | `scraped_at` | UTC timestamp when the record was scraped. | | `locality` | Locality reported by Firmy.cz. | | `postal_code` | Postal code when available. | | `phones` | List of detected phone numbers with `label`, `number`, and `is_primary`. | | `web_url` | Company website URL when available. | | `ico` | Company ICO when available. | | `ares` | ARES enrichment metadata, including matched ICO, business name, legal form, and source URL. | | `data_box` | Company data box ID when available. | | `latitude` | GPS latitude when available. | | `longitude` | GPS longitude when available. | | `rating_value` | Firmy.cz rating value when available. | | `rating_count` | Number of ratings when available. | | `categories` | Company categories from Firmy.cz. | | `source_url` | Source URL used for the record. | | `location_match` | Audit object for strict municipality matching. Present when strict matching is used. | #### Example Output Item ```json { "search_query": "malířství", "name": "Údržba rychle.cz", "phone_primary": "+420 605 778 888", "email": "info@udrzbarychle.cz", "address": "Jiráskova 528/51, 29301, Mladá Boleslav II", "established_at": "2009-10-22", "description": "Zajistíme Vám komplexní servis vaší nemovitosti. Rychle a spolehlivě.", "profile_url": "https://www.firmy.cz/detail/13440564-udrzba-rychle-cz-mlada-boleslav-ii.html", "location": "Mladá Boleslav", "matched_search_queries": ["malířství"], "matched_locations": ["Mladá Boleslav"], "locality": "Mladá Boleslav II", "postal_code": "29301", "phones": [ { "label": "Telefon", "number": "+420 605 778 888", "is_primary": true } ], "web_url": "https://www.udrzbarychle.cz", "ico": "28978013", "ares": { "matched": true, "ico": "28978013", "business_name": "HOLLEN CZ s. r. o.", "legal_form": "112", "source_url": "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/28978013" }, "data_box": "4ide4un", "latitude": 50.423739216064234, "longitude": 14.914580354670488, "categories": ["Úklid, údržba a čištění", "Údržba zeleně a rekultivace"], "location_match": { "is_match": true, "matched_target": "Mladá Boleslav", "actual_locality": "Mladá Boleslav II", "mode": "municipality" } } ``` ### Notes For broad searches, use multiple specific search queries instead of one very general query. Firmy.cz ranking can include nearby or related businesses, so enable `strictLocationMatch` when municipality accuracy is important. When `useApifyProxy` is enabled, the scraper reads Apify proxy settings from the runtime environment and applies them to Firmy.cz and ARES requests. # Actor input Schema ## `searchQuery` (type: `string`): Single search query. Use searchQueries below for multiple queries. Czech characters are supported. ## `searchQueries` (type: `array`): Optional list of search queries to run in one Actor session. When filled, this is used instead of Search query. ## `location` (type: `string`): Single city or municipality name, for example Kladno. Use Locations below for multiple locations. Leave empty to search the whole Czech Republic. ## `locations` (type: `array`): Optional list of city or municipality names to run in one Actor session. When filled, this is used instead of Location. ## `maxResultsPerQuery` (type: `integer`): Maximum number of companies to collect for each search query and location before deduplication. ## `maxResults` (type: `integer`): Backward-compatible alias for Maximum results per query. ## `includeDetails` (type: `boolean`): Open each company profile and enrich the output with detailed fields. ## `strictLocationMatch` (type: `boolean`): Keep only companies whose real locality matches one of the requested municipalities. ## `enrichAres` (type: `boolean`): Look up scraped ICO values in ARES and add established\_at to the output. ## `maxPages` (type: `integer`): Safety limit for listing pagination. ## `delayMinSeconds` (type: `number`): Minimum delay between requests in seconds. ## `delayMaxSeconds` (type: `number`): Maximum delay between requests in seconds. ## `useApifyProxy` (type: `boolean`): Route Firmy.cz and ARES requests through Apify Proxy when proxy credentials are available. ## `listingSource` (type: `string`): Choose the listing source. API uses Firmy.cz frontend FastRPC and falls back to HTML if it fails. ## Actor input object example ```json { "searchQuery": "logistika", "searchQueries": [ "logistika", "autodoprava" ], "locations": [ "Kladno", "Unhost" ], "maxResultsPerQuery": 20, "includeDetails": true, "strictLocationMatch": false, "enrichAres": false, "maxPages": 10, "delayMinSeconds": 1.5, "delayMaxSeconds": 3, "useApifyProxy": false, "listingSource": "api" } ``` # Actor output Schema ## `companies` (type: `string`): Structured company records from Firmy.cz, optionally enriched with ARES data. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQuery": "logistika", "searchQueries": [ "logistika", "autodoprava" ], "location": "", "locations": [ "Kladno", "Unhost" ] }; // Run the Actor and wait for it to finish const run = await client.actor("magistercrane/firmy-cz-crane-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQuery": "logistika", "searchQueries": [ "logistika", "autodoprava", ], "location": "", "locations": [ "Kladno", "Unhost", ], } # Run the Actor and wait for it to finish run = client.actor("magistercrane/firmy-cz-crane-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQuery": "logistika", "searchQueries": [ "logistika", "autodoprava" ], "location": "", "locations": [ "Kladno", "Unhost" ] }' | apify call magistercrane/firmy-cz-crane-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=magistercrane/firmy-cz-crane-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Firmy.cz Crane Scraper", "description": "Scrape company listings and profile details from Firmy.cz by search query and Czech location. Extract names, addresses, phones, emails, websites, ICO, descriptions, categories, GPS coordinates, ratings, and optional ARES establishment dates.", "version": "0.0", "x-build-id": "CgsgigiqdVi9tlqPw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/magistercrane~firmy-cz-crane-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-magistercrane-firmy-cz-crane-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/magistercrane~firmy-cz-crane-scraper/runs": { "post": { "operationId": "runs-sync-magistercrane-firmy-cz-crane-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/magistercrane~firmy-cz-crane-scraper/run-sync": { "post": { "operationId": "run-sync-magistercrane-firmy-cz-crane-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", "properties": { "searchQuery": { "title": "Search query", "type": "string", "description": "Single search query. Use searchQueries below for multiple queries. Czech characters are supported." }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Optional list of search queries to run in one Actor session. When filled, this is used instead of Search query.", "items": { "type": "string" } }, "location": { "title": "Location", "type": "string", "description": "Single city or municipality name, for example Kladno. Use Locations below for multiple locations. Leave empty to search the whole Czech Republic." }, "locations": { "title": "Locations", "type": "array", "description": "Optional list of city or municipality names to run in one Actor session. When filled, this is used instead of Location.", "items": { "type": "string" } }, "maxResultsPerQuery": { "title": "Maximum results per query", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of companies to collect for each search query and location before deduplication.", "default": 20 }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Backward-compatible alias for Maximum results per query." }, "includeDetails": { "title": "Include company details", "type": "boolean", "description": "Open each company profile and enrich the output with detailed fields.", "default": true }, "strictLocationMatch": { "title": "Strict location match", "type": "boolean", "description": "Keep only companies whose real locality matches one of the requested municipalities.", "default": false }, "enrichAres": { "title": "Enrich from ARES", "type": "boolean", "description": "Look up scraped ICO values in ARES and add established_at to the output.", "default": false }, "maxPages": { "title": "Maximum pages", "minimum": 1, "maximum": 250, "type": "integer", "description": "Safety limit for listing pagination.", "default": 10 }, "delayMinSeconds": { "title": "Minimum delay", "minimum": 0, "type": "number", "description": "Minimum delay between requests in seconds.", "default": 1.5 }, "delayMaxSeconds": { "title": "Maximum delay", "minimum": 0, "type": "number", "description": "Maximum delay between requests in seconds.", "default": 3 }, "useApifyProxy": { "title": "Use Apify Proxy", "type": "boolean", "description": "Route Firmy.cz and ARES requests through Apify Proxy when proxy credentials are available.", "default": false }, "listingSource": { "title": "Listing source", "enum": [ "api", "html" ], "type": "string", "description": "Choose the listing source. API uses Firmy.cz frontend FastRPC and falls back to HTML if it fails.", "default": "api" } } }, "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 } } } } } } } } } } ```