Firmy.cz Crane Scraper

Deploying outside Apify? The same scraper runs as an HTTP service on Render or Vercel — see docs/DEPLOYMENT.md.

What Does Firmy.cz Scraper Do?

Firmy.cz Scraper extracts company listings and company profile details from 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

{
  "searchQueries": ["logistika", "autodoprava"],
  "locations": ["Kladno", "Unhost"],
  "maxResultsPerQuery": 20,
  "includeDetails": true,
  "strictLocationMatch": true,
  "enrichAres": true,
  "useApifyProxy": false,
  "listingSource": "api",
  "maxConcurrency": 5
}

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 or Praha. Leave empty to search the whole Czech Republic. If a name is shared by several municipalities, add a district hint (Lány, Kladno).
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.
maxConcurrency	integer	How many company detail pages to fetch at the same time. Default is 5, maximum 16. Only applies when includeDetails is enabled.
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:

search_query
name
phone_primary
phones_all
phones
email
address
established_at
description
profile_url

phone_primary is whichever number Firmy.cz lists first, which is frequently a switchboard or secretariat rather than the line you want. Larger companies publish several numbers with roles, so treat phones_all / phones as the real contact data and phone_primary as a convenience default.

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. Czech numbers are normalized to +420 NNN NNN NNN on every code path; anything unrecognized is passed through unchanged rather than reformatted.
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_all	Every detected number with its label, flattened to one line (Sekretariát: +420 314 006 444 | Obchod: +420 724 938 822). Use this in spreadsheet exports, where the nested phones list is invisible.
phones	List of detected phone numbers with label, number, and is_primary. Use this for automation — the labels are what make an automated pick possible.
web_url	Company website URL when available.
ico	Company ICO when available.
ares	ARES enrichment metadata: matched ICO, business name, legal form, source URL, plus is_active and in_liquidation.
ares.is_active	false when ARES lists the subject as dissolved (ZANIKLY in the ROS master register). Records are flagged, never dropped — filter on this before calling a lead.
ares.in_liquidation	true when the registered business name says v likvidaci or v konkursu. Independent of is_active: a company can be in liquidation while still formally active.
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 describing how the company's locality was matched. Always present. mode is municipality for a city/district/region search and country for a whole-country search, where every locality is in scope.

Example Output Item

{
  "search_query": "malířství",
  "name": "Údržba rychle.cz",
  "phone_primary": "+420 605 778 888",
  "phones_all": "Telefon: +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",
    "is_active": true,
    "in_liquidation": false,
    "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 treats the location as a ranking hint rather than a hard filter, so an unfiltered search for a city routinely returns companies from elsewhere in the country. Enable strictLocationMatch whenever municipality accuracy matters. With it enabled, companies that the listing already places outside the requested municipality are skipped without opening their detail page, so strict runs are also faster than unfiltered ones.

Detail pages dominate the runtime of a run with includeDetails enabled, and they are fetched maxConcurrency at a time. The default of 5 is roughly 3-4x faster than sequential fetching while staying polite; results keep listing order regardless. Raise it for large one-off jobs, lower it to 1 if Firmy.cz starts rate-limiting you.

Caching detail pages

Set SCRAPE_CACHE_PATH to a writable file path and detail pages are reused across runs instead of being re-fetched. On a repeated query this is roughly 5x faster again.

It is off by default on purpose. Lead data goes stale — phone numbers and addresses change — so serving a cached record is a trade you have to opt into. Entries expire after SCRAPE_CACHE_TTL_DAYS (default 30), and a cached record keeps its original scraped_at, so you can always tell how old a lead is. Failed fetches are never cached.

When useApifyProxy is enabled, the scraper reads Apify proxy settings from the runtime environment and applies them to Firmy.cz and ARES requests. Requests to both are retried with exponential backoff on 429 and 5xx responses.