# Firmy.cz Business Directory Scraper (`automation-lab/firmy-cz-business-directory-scraper`) Actor

🇨🇿 Extract Czech business leads from Firmy.cz listings with phones, websites, addresses, ratings, opening hints, and coordinates.

- **URL**: https://apify.com/automation-lab/firmy-cz-business-directory-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.03 / 1,000 item extracteds

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/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

## Firmy.cz Business Directory Scraper

Extract Czech company leads from Firmy.cz public search and category listings.

Firmy.cz Business Directory Scraper helps sales, recruiting, agency, and local-market teams turn Firmy.cz result pages into structured datasets with business names, profile URLs, categories, addresses, phones, websites, ratings, reviews, opening hints, coordinates, and descriptions.

### What does Firmy.cz Business Directory Scraper do?

This actor searches public Firmy.cz listings and saves one dataset row per business.

It supports keyword searches such as `restaurace Praha`, `autoservis Brno`, or `účetní Ostrava`.

It also supports direct Firmy.cz search or category URLs.

The actor follows pagination until it reaches your `maxItems` limit.

It reads server-rendered listing data, so no browser is needed for the default workflow.

### Who is it for?

- 🧭 Local lead generation teams building Czech prospect lists.
- 📞 Sales ops teams enriching CRM accounts with phones and websites.
- 🏢 Agencies researching restaurants, clinics, trades, and local services.
- 👥 Recruiters mapping employers in specific Czech cities or categories.
- 📊 Market researchers tracking local business density and ratings.

### Why use it?

Firmy.cz contains local business profiles that are useful for outreach and market mapping.

Manual copy-paste is slow and inconsistent.

This scraper produces normalized rows that can be exported to CSV, Excel, Google Sheets, BI tools, or CRMs.

### What data can you extract?

| Field | Description |
| --- | --- |
| `name` | Business name |
| `profileUrl` | Firmy.cz detail URL |
| `businessId` | Numeric Firmy.cz ID parsed from the profile URL |
| `categories` | Listing tags such as Restaurace or Autoservisy |
| `address` | Human-readable address |
| `phone` | Public phone number when listed |
| `website` | External website from the listing metadata |
| `ratingValue` | Rating converted to a 0-5 scale |
| `reviewCount` | Number of reviews |
| `openingStatus` | Open/closed text shown on the listing |
| `latitude`, `longitude` | Coordinates from embedded metadata |
| `description` | Business description/snippet |

### How much does it cost to scrape Firmy.cz business leads?

The actor uses pay-per-event pricing.

There is a $0.005 start fee for each run.

Each saved business listing is charged as an item event with tiered per-item pricing:

| Plan tier | Price per saved listing |
| --- | ---: |
| FREE | $0.000065997 |
| BRONZE | $0.000057389 |
| SILVER | $0.000044763 |
| GOLD | $0.000034433 |
| PLATINUM | $0.000022956 |
| DIAMOND | $0.000016069 |

Example cost before platform plan discounts: 100 saved listings on BRONZE cost about $0.0107 total ($0.005 start + 100 × $0.000057389). 1,000 saved listings on BRONZE cost about $0.0624 total.

For best cost control, start with a small `maxItems` value and increase it after checking the first dataset.

### How to use it

1. Open the actor on Apify.
2. Add one or more search queries, for example `restaurace Praha`.
3. Optionally add Firmy.cz category/search URLs.
4. Set `maxItems`.
5. Keep `includeDetails` disabled for the fastest default run.
6. Run the actor.
7. Download the dataset as CSV, JSON, Excel, or connect it to your workflow.

### Input

#### `searchQueries`

Firmy.cz keyword searches.

Examples:

- `restaurace Praha`
- `autoservis Brno`
- `zubní ordinace Ostrava`
- `účetní Plzeň`

#### `startUrls`

Firmy.cz URLs for search or category pages.

Use this when you already have a specific category path.

#### `maxItems`

Maximum businesses to save across all inputs.

#### `includeDetails`

When enabled, the actor visits each profile page and extracts visible email addresses if present.

This adds extra requests, so use it only when emails are important.

### Output example

```json
{
  "name": "Amiata - La Cucina Toscana",
  "profileUrl": "https://www.firmy.cz/detail/13957569-amiata-la-cucina-toscana-praha-vinohrady.html",
  "businessId": "13957569",
  "sourceQuery": "restaurace Praha",
  "categories": ["Restaurace"],
  "address": "Londýnská 608/52, Praha, Vinohrady",
  "phone": "+420 222514141",
  "website": "https://www.amiata.cz/cs/",
  "ratingValue": 5,
  "reviewCount": 18,
  "latitude": 50.07521438598633,
  "longitude": 14.433701515197754
}
````

### Tips for better results

- Use Czech keywords for best coverage.
- Combine service and city names.
- Use category URLs when you need a narrow vertical.
- Keep `includeDetails` off for broad lead collection.
- Increase `maxItems` gradually.

### Integrations

Use this actor with:

- Google Sheets for lead review.
- HubSpot or Pipedrive for sales prospecting.
- Clay or Make for enrichment workflows.
- BI dashboards for local-market analysis.
- Webhooks for scheduled lead exports.

### API usage

#### Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/firmy-cz-business-directory-scraper').call({
  searchQueries: ['restaurace Praha'],
  maxItems: 50
});
console.log(run.defaultDatasetId);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('automation-lab/firmy-cz-business-directory-scraper').call({
    'searchQueries': ['autoservis Brno'],
    'maxItems': 50,
})
print(run['defaultDatasetId'])
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~firmy-cz-business-directory-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"searchQueries":["restaurace Praha"],"maxItems":50}'
```

### MCP usage

Use the Apify MCP server with Claude Desktop or Claude Code:

```text
https://mcp.apify.com/?tools=automation-lab/firmy-cz-business-directory-scraper
```

Claude Code CLI setup:

```bash
claude mcp add --transport http apify-firmy-cz https://mcp.apify.com/?tools=automation-lab/firmy-cz-business-directory-scraper
```

Claude Desktop JSON config:

```json
{
  "mcpServers": {
    "apify-firmy-cz": {
      "url": "https://mcp.apify.com/?tools=automation-lab/firmy-cz-business-directory-scraper"
    }
  }
}
```

Example prompts:

- "Scrape 100 restaurant leads from Firmy.cz in Prague."
- "Find autoservis businesses in Brno and export names, phones, and websites."
- "Create a Czech local lead list from this Firmy.cz category URL."

### Scheduling

Schedule the actor weekly or monthly to refresh local lead lists.

Use small scheduled batches for city/category monitoring.

For CRM syncs, trigger downstream automations from the dataset-ready webhook.

### Data quality notes

Firmy.cz profiles vary by business.

Some listings have phone numbers and websites.

Some listings only provide address and description.

Ratings are converted from Firmy.cz percent values to a 0-5 scale for convenience.

### FAQ

#### Is this a Firmy.cz scraper for Czech company leads?

Yes. It is designed for public Firmy.cz search and category listings.

#### Does it require a Firmy.cz account?

No. The default workflow uses public pages only.

### Troubleshooting

#### Why did I get fewer results than `maxItems`?

The query or category may have fewer public listings, or Firmy.cz may stop pagination earlier than expected.

Try a broader query or a different city/category.

#### Why are emails missing?

Firmy.cz listing pages do not always expose emails.

Enable `includeDetails` to scan profile pages, but many businesses still publish only phone and website.

#### Why is the website URL different from the button URL?

Tracking parameters are stripped where possible so users get cleaner website links.

### Legality and responsible use

This actor extracts publicly available Firmy.cz business listing data.

Use the data in accordance with applicable laws, privacy rules, Firmy.cz terms, and outreach regulations.

For EU outreach, make sure your processing has a lawful basis and respect opt-out requests.

### Related Automation Lab scrapers

- [Google Maps Lead Finder](https://apify.com/automation-lab/google-maps-lead-finder)
- [ARES Czech Registry Scraper](https://apify.com/automation-lab/ares-czech-registry-scraper)
- [Das Telefonbuch Business Scraper](https://apify.com/automation-lab/das-telefonbuch-business-scraper)
- [GoYellow Scraper](https://apify.com/automation-lab/goyellow-scraper)

### Limitations

The actor focuses on public search and category listings.

It does not log in.

It does not bypass private contact forms.

It does not guarantee email extraction.

### Changelog

#### 0.1

Initial private development build with HTTP extraction, pagination, listing metadata, optional detail-page email scan, and Firmy.cz-focused input schema.

### Support

If a query stops working, save the input and run ID.

Include the Firmy.cz URL or keyword, expected result count, and sample missing business when reporting an issue.

# Actor input Schema

## `searchQueries` (type: `array`):

Firmy.cz search terms such as restaurace Praha, účetní Brno, or autoservis Ostrava. Each query starts at https://www.firmy.cz/?q=... and follows pagination until maxItems is reached.

## `startUrls` (type: `array`):

Optional Firmy.cz search or category result URLs to crawl, for example https://www.firmy.cz/Restauracni-a-pohostinske-sluzby/Restaurace?q=restaurace+praha.

## `maxItems` (type: `integer`):

Maximum number of business listing records to save across all queries and URLs.

## `includeDetails` (type: `boolean`):

When enabled, the actor opens each Firmy.cz profile page and extracts visible email addresses if present. This is slower and costs more requests.

## Actor input object example

```json
{
  "searchQueries": [
    "restaurace Praha"
  ],
  "startUrls": [],
  "maxItems": 20,
  "includeDetails": false
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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 = {
    "searchQueries": [
        "restaurace Praha"
    ],
    "startUrls": [],
    "maxItems": 20,
    "includeDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/firmy-cz-business-directory-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 = {
    "searchQueries": ["restaurace Praha"],
    "startUrls": [],
    "maxItems": 20,
    "includeDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/firmy-cz-business-directory-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 '{
  "searchQueries": [
    "restaurace Praha"
  ],
  "startUrls": [],
  "maxItems": 20,
  "includeDetails": false
}' |
apify call automation-lab/firmy-cz-business-directory-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/firmy-cz-business-directory-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Firmy.cz Business Directory Scraper",
        "description": "🇨🇿 Extract Czech business leads from Firmy.cz listings with phones, websites, addresses, ratings, opening hints, and coordinates.",
        "version": "0.1",
        "x-build-id": "yPewGBoFTNsg6CtkE"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~firmy-cz-business-directory-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-firmy-cz-business-directory-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/automation-lab~firmy-cz-business-directory-scraper/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-firmy-cz-business-directory-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/automation-lab~firmy-cz-business-directory-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-firmy-cz-business-directory-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": {
                    "searchQueries": {
                        "title": "Search queries",
                        "type": "array",
                        "description": "Firmy.cz search terms such as restaurace Praha, účetní Brno, or autoservis Ostrava. Each query starts at https://www.firmy.cz/?q=... and follows pagination until maxItems is reached.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "startUrls": {
                        "title": "Firmy.cz start URLs",
                        "type": "array",
                        "description": "Optional Firmy.cz search or category result URLs to crawl, for example https://www.firmy.cz/Restauracni-a-pohostinske-sluzby/Restaurace?q=restaurace+praha.",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "maxItems": {
                        "title": "Maximum businesses",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Maximum number of business listing records to save across all queries and URLs.",
                        "default": 20
                    },
                    "includeDetails": {
                        "title": "Visit detail pages for extra emails",
                        "type": "boolean",
                        "description": "When enabled, the actor opens each Firmy.cz profile page and extracts visible email addresses if present. This is slower and costs more requests.",
                        "default": false
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```