# Pai.pt Portugal Business Directory Finder (`nimbryxo-studio/pai-pt-portugal-business-directory-finder`) Actor

Search pai.pt (Páginas Amarelas) by category and Portuguese city or concelho, or nationwide, and optionally pull each business's email, website, coordinates, and opening hours.

- **URL**: https://apify.com/nimbryxo-studio/pai-pt-portugal-business-directory-finder.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Lead generation, Automation, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.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

## Pai.pt Portugal Business Directory Finder

Pai.pt (Páginas Amarelas) lists businesses across every district of Portugal, but browsing by trade and city on the site itself means paging through results by hand. This actor searches pai.pt by category and city or concelho — or nationwide — and can enrich each result with the fuller profile data (email, website, coordinates, tags) that only lives on the business's own page.

### What this actor does

- Searches by business category and a Portuguese city or concelho, or leaves location blank to search all of Portugal at once.
- Offers over 30 curated categories and 34 curated cities/concelhos as ready-to-pick options, with free-text overrides for any category or location slug not on those lists.
- Optionally visits each result's own profile page to add email, website, GPS coordinates, full category/tag lists, and an "about" description.
- Filters results to businesses currently open (computed from their published hours in the Europe/Lisbon timezone) or at or above a minimum star rating.
- Only includes a field when pai.pt actually published that value for the business, rather than sending it empty.

### Output per business

| Field | Description |
|---|---|
| `name` | Business name |
| `category` | Category text shown on the search-results card (search mode) |
| `cardDescription` | Short tagline from the search card, when it differs from the name (search mode; replaced by `description` once a profile is fetched) |
| `categories` | All registered categories (profile lookups) |
| `tags` | The business's own keyword tags (profile lookups) |
| `verticals` | Pai.pt's broader industry vertical(s) for the business (profile lookups) |
| `description` | The business's own "about" text, when published (profile lookups) |
| `street`, `postalCode`, `city`, `fullAddress` | Address fields, when the source card or profile page shows them |
| `latitude`, `longitude` | GPS coordinates (profile lookups) |
| `phone` | Phone number, shown on both the search card and profile page |
| `email`, `website` | Contact details available only from the business's own profile page |
| `imageUrl`, `logoUrl` | Listing and logo images |
| `openingHours` | Structured opening hours per time window |
| `openingHoursText` | One-line summary of the weekly schedule |
| `isOpenNow` | Whether the business is open right now, computed from `openingHours` in the Europe/Lisbon timezone |
| `rating`, `reviewCount` | Average star rating and review count, once the business has at least one review |
| `searchCategory`, `searchLocation` | The category and location used for this search (search mode only) |
| `sourceUrl` | Canonical pai.pt profile URL |
| `recordType` | Always `"business"` |
| `scrapedAt` | UTC timestamp of the scrape |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` (category + location) or `detail` (fetch specific profile URLs). |
| `category` | string | `restaurantes` | One of 30+ curated categories, or `custom` to use `customCategory`. |
| `customCategory` | string | – | Free-text pai.pt category slug, overriding `category` when set. |
| `location` | string | – (nationwide) | One of 34 curated cities/concelhos, `custom` to use `customLocation`, or blank for all of Portugal. |
| `customLocation` | string | – | Free-text pai.pt location slug, overriding `location` when set. |
| `sortBy` | string | `ranked` | `ranked` (pai.pt's default ranking) or `popular` (most popular). |
| `openNowOnly` | boolean | `false` | Keep only businesses currently open. Businesses with no published hours are still included. |
| `minRating` | string | – (no minimum) | Keep only businesses rated at least this many stars (`1`-`5`). Businesses with no rating are still included. |
| `fetchDetails` | boolean | `true` | Visit each result's own profile page for email, website, coordinates, and full category/tag lists. |
| `businessUrls` | array | `[]` | Pai.pt business profile URLs to fetch directly, in `detail` mode. |
| `maxItems` | integer | `20` | Maximum number of business records to return. |

#### Example: restaurants in Lisbon

```json
{
  "mode": "search",
  "category": "restaurantes",
  "location": "lisboa",
  "maxItems": 30
}
```

#### Example: highly rated veterinarians in Porto, open now

```json
{
  "mode": "search",
  "category": "veterinarios",
  "location": "porto",
  "minRating": "4",
  "openNowOnly": true,
  "maxItems": 30
}
```

#### Example: fast name-only scan without profile fetching

```json
{
  "mode": "search",
  "category": "cafes",
  "location": "coimbra",
  "fetchDetails": false,
  "maxItems": 100
}
```

#### Example: specific business profiles

```json
{
  "mode": "detail",
  "businessUrls": [
    { "url": "https://www.pai.pt/paginas/161409-restaurantes-pezarroz" }
  ]
}
```

### Use cases

- **Trade lead generation** — build a prospect list of electricians, lawyers, or restaurants by concelho for outreach.
- **Local market research** — compare business density and ratings for a category across Portuguese cities.
- **Directory or comparison-site building** — feed structured Portuguese business listings into your own local-search product.
- **Competitor mapping** — see who else operates in a category and area, with hours and contact details.
- **Franchise and site-selection analysis** — check how saturated a concelho already is for a service before opening there.

### FAQ

**Where does this data come from, and is it affiliated with pai.pt?**
It reads the public search and business-profile pages on pai.pt (Páginas Amarelas), Portugal's business directory. This actor is independent and not affiliated with or endorsed by pai.pt.

**Why do some businesses have no rating?**
Pai.pt only shows a rating once a business has received at least one review, so a business with none simply has no `rating`/`reviewCount` fields rather than a misleading `0`.

**What's the difference between `category` and `categories`?**
`category` is the single text label shown on the search card. `categories` is the full list of categories registered on the business's profile page, and only appears when a profile is fetched (`fetchDetails: true`, or always in `detail` mode).

**Can I search all of Portugal instead of one city?**
Yes — leave `location` blank to search a category nationwide instead of scoping to a city or concelho.

**Why is `fetchDetails` on by default?**
Email, website, coordinates, and full category/tag lists only live on a business's own profile page. The search card already carries phone and address, so those fields populate even with `fetchDetails: false` — turn it off only if you want a faster scan and don't need the rest.

**How is `isOpenNow` worked out?**
This actor computes it from the business's own published opening hours, checked against the current time in the Europe/Lisbon timezone. If no hours are published, the field is left off rather than guessed.

**What happens with a category or location that doesn't exist on pai.pt?**
An unrecognized category returns zero results. An unrecognized location is handled by pai.pt itself, which falls back to a nationwide result set for the category rather than erroring — double-check your location slug if you need city-scoped results.

**Why does `category: "dentistas"` combined with a location return nothing?**
This is a quirk of pai.pt's own category tree, not an actor bug. Individual dentists on pai.pt are filed under the broader "clinicas-e-especialidades-medicas" category and only tagged with the keyword "dentista" — there's no `dentistas` node for a specific city. The nationwide `dentistas` search still works because pai.pt resolves it as a keyword search across the whole country. To find dentists in a specific city, search `dentistas` nationwide and filter the results by `city` yourself, or use `customCategory: "clinicas-e-especialidades-medicas"` with a location (note this broader category covers other medical specialties too, not dentists exclusively).

# Actor input Schema

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

What to fetch: search a category + location, or fetch full business profiles from direct URLs.

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

Business category to search for. Pick a common category from the list, or choose 'Custom category' and type your own slug below (mode=search).

## `customCategory` (type: `string`):

Free-text pai.pt category URL slug not in the curated list above, e.g. 'canalizadores' or 'oficinas-auto' (mode=search). Takes priority over 'Category' when set.

## `location` (type: `string`):

Portuguese city or concelho to search in. Leave as 'Any location (nationwide)' to search the category across all of Portugal (mode=search).

## `customLocation` (type: `string`):

Free-text pai.pt location URL slug not in the curated list above, e.g. 'vila-franca-de-xira' or 'peniche' (mode=search). Takes priority over 'Location' when set.

## `sortBy` (type: `string`):

How to order search results (mode=search).

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

Only return businesses that are currently open, computed from each business's opening hours in the Europe/Lisbon timezone (mode=search). Businesses with no published hours are still included.

## `minRating` (type: `string`):

Only return businesses rated at least this many stars, e.g. '4' for 4.0+. Businesses with no rating are still included (ratings are only shown on pai.pt once a business has reviews).

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

For each search result, also visit its business profile page to collect address, phone, email, website, coordinates, and full category/tag lists. Recommended -- disable only for a faster, name-only preview scan (mode=search).

## `businessUrls` (type: `array`):

Direct pai.pt business profile URLs to fetch, e.g. https://www.pai.pt/paginas/161409-restaurantes-pezarroz. Use the 'sourceUrl' field from search results.

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

Hard cap on the number of business records to return.

## Actor input object example

```json
{
  "mode": "search",
  "category": "restaurantes",
  "location": "lisboa",
  "sortBy": "ranked",
  "openNowOnly": false,
  "minRating": "",
  "fetchDetails": true,
  "businessUrls": [],
  "maxItems": 20
}
```

# Actor output Schema

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

Dataset containing all scraped pai.pt business listings.

# 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": "restaurantes",
    "location": "lisboa",
    "sortBy": "ranked",
    "openNowOnly": false,
    "minRating": "",
    "fetchDetails": true,
    "businessUrls": [],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/pai-pt-portugal-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": "restaurantes",
    "location": "lisboa",
    "sortBy": "ranked",
    "openNowOnly": False,
    "minRating": "",
    "fetchDetails": True,
    "businessUrls": [],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/pai-pt-portugal-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": "restaurantes",
  "location": "lisboa",
  "sortBy": "ranked",
  "openNowOnly": false,
  "minRating": "",
  "fetchDetails": true,
  "businessUrls": [],
  "maxItems": 20
}' |
apify call nimbryxo-studio/pai-pt-portugal-business-directory-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/pai-pt-portugal-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/LxphDGYpcMil77ktQ/builds/bjca6XqmexsPYakP0/openapi.json
