# PanoramaFirm.pl Polish Business Directory Finder (`vexaloom-labs/panoramafirm-pl-polish-business-directory-finder`) Actor

Search PanoramaFirm.pl by category and city or nationwide, or fetch specific profile URLs, with address, phone, website, opening hours, rating, tax ID, and coordinates per business.

- **URL**: https://apify.com/vexaloom-labs/panoramafirm-pl-polish-business-directory-finder.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Lead generation, Automation, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 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.
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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## PanoramaFirm.pl Polish Business Directory Finder

PanoramaFirm.pl is one of Poland's largest business directories: trades and professions organized by city, county, and voivodeship, with phone numbers, websites, tax IDs, ratings, reviews, and profile galleries. This actor turns that directory into structured business rows for lead generation, local SEO, CRM enrichment, and market research.

It searches by category or free-text keyword, combines many terms with many Polish locations in one run, paginates automatically, and can either read the results pages only (fast) or open every business profile for the full record (rich).

### What this actor does

- Searches a curated category or any Polish keyword, in one location or across the whole country.
- Cross-joins `searchTerms` with `locations`, so one run can collect, for example, `hydraulik` × `Warszawa`, `Kraków`, and `pomorskie`.
- Accepts PanoramaFirm search URLs and business profile URLs directly, including result-page URLs.
- Sorts by popularity, highest rating, or alphabetically, and filters to currently open businesses or a minimum rating.
- Optionally visits every business profile to add NIP, opening hours, coordinates, full descriptions, review text, social links, and photo/video galleries.
- Handles Polish diacritics (ą, ć, ę, ł, ń, ó, ś, ź, ż) in both search input and output.
- Leaves a field out of a record whenever the business never published that value — no empty strings, nulls, or placeholder values.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` for the directory, `byUrl` for explicit PanoramaFirm URLs. |
| `category` | string | `hydraulicy` | Curated trade to browse when `searchTerms` is empty. |
| `searchTerms` | array | `[]` | Keywords or trades in Polish, e.g. `hydraulik`, `restauracja`, `montaż klimatyzacji`. |
| `locations` | array | `[]` | Cities, counties, or voivodeships, e.g. `Warszawa`, `Kraków`, `pomorskie`. |
| `city` | string | `warszawa` | Curated city used when `locations` is empty; choose "Whole Poland" for nationwide. |
| `startUrls` | array | `[]` | PanoramaFirm search-results URLs or business profile URLs. |
| `fetchDetails` | boolean | `true` | Open each profile for NIP, hours, coordinates, reviews, galleries, and descriptions. |
| `sort` | string | `popularity` | `popularity`, `rating`, `az`, or `za`. |
| `openNowOnly` | boolean | `false` | Keep only businesses currently marked open. |
| `minRating` | integer | – | Keep only businesses rated at or above this value (1–5). |
| `minReviewCount` | integer | `0` | Keep only businesses with at least this many reviews. |
| `requireWebsite` | boolean | `false` | Drop businesses without a website. |
| `requirePhone` | boolean | `false` | Drop businesses without a phone number. |
| `requireEmail` | boolean | `false` | Drop businesses without an email address. |
| `maxItems` | integer | `50` | Hard cap on emitted business records (1–1000). |
| `maxPages` | integer | `40` | Safety cap on 25-result pages read per term/location. |
| `maxConcurrency` | integer | `5` | Number of business profiles fetched in parallel. |

#### Example: one trade across several cities

```json
{
  "mode": "search",
  "searchTerms": ["hydraulik"],
  "locations": ["Warszawa", "Kraków", "pomorskie"],
  "fetchDetails": true,
  "maxItems": 150
}
```

#### Example: highly rated restaurants with a website

```json
{
  "mode": "search",
  "category": "restauracje",
  "city": "krakow",
  "sort": "rating",
  "minRating": 4,
  "minReviewCount": 5,
  "requireWebsite": true,
  "maxItems": 100
}
```

#### Example: fetch specific profiles or a saved search URL

```json
{
  "mode": "byUrl",
  "startUrls": [
    "https://panoramafirm.pl/hydraulicy/,,warszawa/firmy,2.html",
    "https://panoramafirm.pl/mazowieckie,płoński,popielżyn_dolny,14/hyd_bud_pawel_brzeszkiewicz-sbjbzz_fhm.html"
  ],
  "fetchDetails": true,
  "maxItems": 50
}
```

### Output per business

| Field | Description |
|---|---|
| `name` | Business name |
| `category`, `categorySlug`, `categories` | Industry label and PanoramaFirm category slug |
| `address`, `street`, `city`, `postalCode`, `county`, `voivodeship`, `country` | Split postal address |
| `phone`, `website`, `email` | Contact details when published |
| `nip` | Polish tax identification number (profile lookups) |
| `rating`, `reviewCount` | Average rating and number of reviews |
| `reviews` | Up to ten recent reviews with author, rating, date, and text (profile lookups) |
| `openingHours` | Weekly hours as `{day, opens, closes}` entries, when PanoramaFirm publishes structured hours |
| `description`, `servicesDescription`, `serviceArea` | Business description, services, and service area (profile lookups) |
| `latitude`, `longitude` | GPS coordinates (profile lookups) |
| `facebookUrl`, `instagramUrl`, `linkedinUrl`, `youtubeUrl`, `tiktokUrl`, `twitterUrl`, `googleMapsUrl` | Social and map links when published |
| `logoUrl`, `galleryImages`, `videoUrls`, `certificateImages` | Logo, gallery photos, YouTube videos, and certificate images |
| `profileUrl`, `slug`, `companyId` | Canonical profile URL, PanoramaFirm slug, and internal company ID |
| `searchTerm`, `searchLocation` | Which input term and location produced the row |
| `recordType`, `scrapedAt` | Record marker and UTC scrape timestamp |

### Use cases

- **B2B lead generation** — build prospect lists by trade across many Polish cities in one run.
- **Local SEO auditing** — compare a client's listing with competitors in the same category and location.
- **CRM enrichment** — attach verified phone, email, address, NIP, and coordinates to existing records.
- **Market density research** — count competitors by trade, city, county, or voivodeship.
- **Directory aggregation** — normalize Polish business data into a wider listings product.

### FAQ

**Do I need an account, cookies, or an API key?**
No. PanoramaFirm.pl is a public directory; this actor needs no login, key, or browser.

**Do I need to configure a proxy?**
No. The actor connects directly and only switches to Apify Proxy automatically if PanoramaFirm temporarily rejects a request.

**Which categories and locations are supported?**
The dropdowns are shortcuts for common trades and cities, but `searchTerms` and `locations` accept any Polish keyword, city, county, or voivodeship that PanoramaFirm recognizes — including small towns and all 16 voivodeships.

**Why do some businesses have fewer fields than others?**
PanoramaFirm only publishes what each business filled in. A missing phone, email, website, NIP, or hours entry is left out of the record rather than emitted as a placeholder.

**Can `openNowOnly` return zero results even when the category has businesses in that city?**
Yes. PanoramaFirm's "open now" listing is not scoped as tightly to the selected category and location as a normal search, so combining it with narrow filters can genuinely return nothing. Try widening the filters or turning `openNowOnly` off.

**Are opening hours always available?**
Only when PanoramaFirm publishes structured hours for that profile. Many profiles show hours only in free-text descriptions, in which case the actor does not guess them.

**Can I re-fetch a business I already have a URL for?**
Yes — use `mode: "byUrl"` with profile URLs, or paste a results-page URL to resume a search from any page.

**How fresh is the data?**
Each run reads PanoramaFirm's live pages, so results reflect what is currently published.

**Is this affiliated with PanoramaFirm.pl?**
No. This actor reads PanoramaFirm.pl's public pages and is not affiliated with, endorsed by, or connected to PanoramaFirm.pl.

# Actor input Schema

## `mode` (type: `string`):

Search the directory, or fetch specific PanoramaFirm URLs.

## `category` (type: `string`):

Category to browse when `searchTerms` is empty. Pick one of the curated Polish trades.

## `searchTerms` (type: `array`):

What to look for, in Polish: a trade or any keyword, e.g. `hydraulik`, `restauracja`, `montaż klimatyzacji`. Every term is searched in every location. When set, `category` is ignored.

## `locations` (type: `array`):

Polish cities, counties or voivodeships, e.g. `Warszawa`, `Kraków`, `pomorskie`. Each term is combined with every location. Leave empty to use `city`, or to search all of Poland.

## `city` (type: `string`):

Restrict results to a curated city when `locations` is empty. Choose "Whole Poland" for a nationwide search.

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

PanoramaFirm search-results URLs (including page URLs) or business profile URLs. Search URLs paginate automatically.

## `sort` (type: `string`):

How PanoramaFirm should order results before they're scraped. Only affects which businesses are emitted first when `maxItems` truncates the result set.

## `openNowOnly` (type: `boolean`):

Only keep businesses PanoramaFirm currently marks as open (based on their published opening hours).

## `fetchDetails` (type: `boolean`):

Visit each business's profile page to also collect opening hours, description, NIP, GPS coordinates, videos, galleries, and full review data. Slower but richer. Turn off for a fast, listing-only scrape.

## `minRating` (type: `integer`):

Only keep businesses with a rating at or above this value (1-5). Businesses with no rating yet are excluded when this is set.

## `minReviewCount` (type: `integer`):

Only keep businesses with at least this many customer reviews. 0 disables the filter.

## `requireWebsite` (type: `boolean`):

Drop businesses that don't publish a website.

## `requirePhone` (type: `boolean`):

Drop businesses that don't publish a phone number.

## `requireEmail` (type: `boolean`):

Drop businesses that don't publish an email address.

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

Hard cap on the number of business records emitted.

## `maxPages` (type: `integer`):

Safety cap on how many 25-result pages are read for each search term and location.

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

How many business profiles to fetch at the same time. Lower it if you see rate limiting.

## Actor input object example

```json
{
  "mode": "search",
  "category": "hydraulicy",
  "searchTerms": [],
  "locations": [],
  "city": "warszawa",
  "startUrls": [],
  "sort": "popularity",
  "openNowOnly": false,
  "fetchDetails": true,
  "minReviewCount": 0,
  "requireWebsite": false,
  "requirePhone": false,
  "requireEmail": false,
  "maxItems": 3,
  "maxPages": 40,
  "maxConcurrency": 5
}
```

# Actor output Schema

## `businesses` (type: `string`):

Dataset containing all scraped PanoramaFirm.pl businesses.

# 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 = {
    "mode": "search",
    "category": "hydraulicy",
    "searchTerms": [],
    "locations": [],
    "city": "warszawa",
    "startUrls": [],
    "sort": "popularity",
    "openNowOnly": false,
    "fetchDetails": true,
    "minReviewCount": 0,
    "requireWebsite": false,
    "requirePhone": false,
    "requireEmail": false,
    "maxItems": 3,
    "maxPages": 40,
    "maxConcurrency": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/panoramafirm-pl-polish-business-directory-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 = {
    "mode": "search",
    "category": "hydraulicy",
    "searchTerms": [],
    "locations": [],
    "city": "warszawa",
    "startUrls": [],
    "sort": "popularity",
    "openNowOnly": False,
    "fetchDetails": True,
    "minReviewCount": 0,
    "requireWebsite": False,
    "requirePhone": False,
    "requireEmail": False,
    "maxItems": 3,
    "maxPages": 40,
    "maxConcurrency": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/panoramafirm-pl-polish-business-directory-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 '{
  "mode": "search",
  "category": "hydraulicy",
  "searchTerms": [],
  "locations": [],
  "city": "warszawa",
  "startUrls": [],
  "sort": "popularity",
  "openNowOnly": false,
  "fetchDetails": true,
  "minReviewCount": 0,
  "requireWebsite": false,
  "requirePhone": false,
  "requireEmail": false,
  "maxItems": 3,
  "maxPages": 40,
  "maxConcurrency": 5
}' |
apify call vexaloom-labs/panoramafirm-pl-polish-business-directory-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/panoramafirm-pl-polish-business-directory-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/1XEKfiPTje3qYkrti/builds/dc8wGb6oVuOO7FFpr/openapi.json
