# PaiPt Scraper - Portugal Business Directory (Paginas Amarelas) (`crawlerbros/paipt-scraper`) Actor Scrape pai.pt (Portugal's Yellow Pages / Paginas Amarelas business directory) listings. Search by category and location (concelho), or fetch full business profiles by URL. Get names, addresses, phone numbers, emails, websites, categories, opening hours, and coordinates. - **URL**: https://apify.com/crawlerbros/paipt-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## PaiPt Scraper - Portugal Business Directory (Paginas Amarelas) Scrape **pai.pt** (Paginas Amarelas) — Portugal's leading business directory. Search any business category in any Portuguese city or concelho and get names, addresses, phone numbers, emails, websites, opening hours, and GPS coordinates. Or fetch full business profiles directly by URL. No login, no cookies, no API key required. ### What this actor does - **Two modes:** `search` (category + location) and `detail` (direct business profile URLs) - **30+ curated categories** to pick from, or type any custom category slug - **34 curated Portuguese cities/concelhos** to pick from, or type any custom location slug — leave blank to search nationwide - **Sort by** default ranking or most popular - **Filter by** "open now" (computed live from each business's published hours) or minimum star rating - **Rich business profiles** — GPS coordinates, structured opening hours, email, website, full category/keyword tags - **Empty fields are omitted** — you only ever see fields that were actually found for a business ### Output per business - `name` — business name - `category` — the category text shown on the search-results card (mode=search) - `cardDescription` — the short tagline shown on the search-results card, when it differs from the business name (mode=search; superseded by `description` once a profile is fetched) - `categories[]` — all registered categories (when profile fetched) - `tags[]` — the business's own keyword tags (when profile fetched) - `verticals[]` — pai.pt's broader industry vertical(s) (when profile fetched) - `description` — the business's own "about" text, when published on its profile (when profile fetched) - `street`, `postalCode`, `city`, `fullAddress` (when profile fetched) - `latitude`, `longitude` — GPS coordinates (when profile fetched) - `phone`, `email`, `website` - `imageUrl`, `logoUrl` - `openingHours[]` — structured opening hours (`{weekday, day, open, close}` per time window) - `openingHoursText` — human-readable opening-hours summary - `isOpenNow` — computed live from `openingHours` in the Europe/Lisbon timezone - `rating`, `reviewCount` — average star rating and number of reviews (only present once a business has received reviews) - `searchCategory`, `searchLocation` — the category/location you searched for (mode=search) - `sourceUrl` — canonical pai.pt profile URL for the business - `recordType: "business"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `search` | `search` (category + location) or `detail` (fetch by URL) | | `category` | string (select) | `restaurantes` | Pick a common category, or `custom` to use `customCategory` (mode=search) | | `customCategory` | string | – | Any free-text category slug, overrides `category` (mode=search) | | `location` | string (select) | – (nationwide) | Pick a common city/concelho, or `custom` to use `customLocation`, or leave blank for all of Portugal (mode=search) | | `customLocation` | string | – | Any free-text location slug, overrides `location` (mode=search) | | `sortBy` | string (select) | `ranked` | `ranked` (default ranking) or `popular` (most popular) | | `openNowOnly` | boolean | `false` | Only return businesses currently open (Europe/Lisbon time) | | `minRating` | string (select) | – (no minimum) | Only return businesses rated at least `1`-`5` stars | | `fetchDetails` | boolean | `true` | Also visit each business's profile page for address, phone, email, website, coordinates, and full tags | | `businessUrls` | array | – | pai.pt profile URLs to fetch directly (mode=detail) | | `maxItems` | int | `20` | Hard cap on returned records (1-2000) | #### Example: search restaurants in Lisbon ```json { "mode": "search", "category": "restaurantes", "location": "lisboa", "maxItems": 30 } ```` #### Example: lawyers nationwide, most popular first ```json { "mode": "search", "category": "advogados", "location": "", "sortBy": "popular", "maxItems": 50 } ``` #### Example: 4+ star veterinarians in Porto, open right now ```json { "mode": "search", "category": "veterinarios", "location": "porto", "minRating": "4", "openNowOnly": true, "maxItems": 30 } ``` #### Example: fast name-only scan (no detail-page enrichment) ```json { "mode": "search", "category": "cafes", "location": "coimbra", "fetchDetails": false, "maxItems": 100 } ``` #### Example: fetch specific business profiles ```json { "mode": "detail", "businessUrls": [ { "url": "https://www.pai.pt/paginas/161409-restaurantes-pezarroz" } ] } ``` ### Use cases - **Local lead generation** — build a prospect list of Portuguese businesses by trade and city for B2B outreach - **Market research** — measure business density for a category across Portuguese cities and concelhos - **Directory aggregation** — feed structured Portuguese business data into your own local-search product - **Competitor mapping** — see who else operates in a category and area, with contact info and hours - **Franchise & site-selection analysis** — evaluate service-business coverage across regions of Portugal ### FAQ **What data source does this actor use?** It reads the publicly available search and business-profile pages on pai.pt (Paginas Amarelas), Portugal's business directory. No account or API key is needed. **Is this affiliated with pai.pt or Paginas Amarelas?** No. This is an independent, third-party actor that reads publicly accessible pages. **Why do some businesses have no rating?** pai.pt only shows a rating once a business has received at least one review. Businesses with no reviews simply omit the `rating`/`reviewCount` fields rather than showing a fake `0`. **What's the difference between `category` and `categories`?** `category` is the single category text shown on the search-results card. `categories` (only populated with `fetchDetails: true`, or always in `detail` mode) lists every category registered on the business's full profile page. **Can I search all of Portugal at once?** Yes — leave `location` blank (or set it to an empty string) to search a category nationwide instead of a single city/concelho. **How accurate are the GPS coordinates?** `latitude`/`longitude` come directly from the business's own pai.pt profile page (only available with `fetchDetails: true` in search mode, or always in `detail` mode). **What is the `description` field?** It's the business's own "about" text, when the business has published one on its pai.pt profile page (only available with `fetchDetails: true` in search mode, or always in `detail` mode). Not every business has written one, so the field is omitted rather than left blank when absent. **Why is `fetchDetails` on by default?** Most of the useful fields — email, website, coordinates, structured `categories`/`tags` — only appear on the business's own profile page, not the search-results card. The search-results card itself already includes `phone` and `street`/`postalCode`/`city`/`fullAddress`, so those are populated even with `fetchDetails: false`. Turn detail-fetching off only if you need a faster scan and don't need email/website/coordinates/full tags. **How is `isOpenNow` calculated?** This actor computes it itself from each business's published `openingHours`, using the current time in the Europe/Lisbon timezone. Businesses that haven't published opening hours simply omit this field rather than guessing. **What happens if I type a location or category that doesn't exist on pai.pt?** An unrecognized category returns 0 results cleanly. An unrecognized location, however, is handled by pai.pt itself, not this actor: pai.pt falls back to a nationwide result set for the category instead of returning an error, so double-check your location spelling against pai.pt's own site if you need location-scoped results. **What locations and categories are supported?** The `location` and `category` dropdowns list the most common Portuguese cities/concelhos and business categories, but pai.pt supports many more. Use `customLocation` / `customCategory` to target any pai.pt category or concelho slug directly (visit pai.pt and copy the slug from its URL, e.g. `pai.pt/canalizadores/vila-franca-de-xira`). **Known limitation: `category: "dentistas"` combined with a `location` returns 0 results.** This is a quirk of pai.pt's own site, not a bug in this actor. On pai.pt, individual dentists aren't filed under a `dentistas` category node in the site's category tree — they're filed under the broader `clinicas-e-especialidades-medicas` (clinics & medical specialties) category and only tagged with the keyword "dentista". The nationwide `pai.pt/dentistas` page still works because pai.pt resolves it as a keyword search across all of Portugal, but pai.pt's own `pai.pt/dentistas/` URL pattern requires an exact category-tree match and returns 0 for every location (confirmed empty for Lisboa, Porto, Braga, and Coimbra alike) — while the identical URL pattern works normally for every other category in the dropdown (e.g. `restaurantes`, `advogados`, `veterinarios`). If you need dentists filtered by city, search `category: "dentistas"` nationwide and filter the results by `city` yourself, or use `customCategory: "clinicas-e-especialidades-medicas"` with a location (note this broader category also includes other medical specialties, 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 '' with your token const client = new ApifyClient({ 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("crawlerbros/paipt-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 = { "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("crawlerbros/paipt-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 '{ "mode": "search", "category": "restaurantes", "location": "lisboa", "sortBy": "ranked", "openNowOnly": false, "minRating": "", "fetchDetails": true, "businessUrls": [], "maxItems": 20 }' | apify call crawlerbros/paipt-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/paipt-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "PaiPt Scraper - Portugal Business Directory (Paginas Amarelas)", "description": "Scrape pai.pt (Portugal's Yellow Pages / Paginas Amarelas business directory) listings. Search by category and location (concelho), or fetch full business profiles by URL. Get names, addresses, phone numbers, emails, websites, categories, opening hours, and coordinates.", "version": "1.0", "x-build-id": "Fx3XDlIBSRdS8fQoS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~paipt-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-paipt-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/crawlerbros~paipt-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-paipt-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/crawlerbros~paipt-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-paipt-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "detail" ], "type": "string", "description": "What to fetch: search a category + location, or fetch full business profiles from direct URLs.", "default": "search" }, "category": { "title": "Category", "enum": [ "custom", "restaurantes", "advogados", "dentistas", "cabeleireiros", "hoteis", "eletricistas", "pintores", "imobiliarias", "funerarias", "fisioterapeutas", "veterinarios", "farmacias", "limpezas", "mudancas", "padarias", "talhos", "ginasios", "clinicas-veterinarias", "arquitetos", "notarios", "seguros", "psicologos", "pastelarias", "cafes", "bares", "pizzarias", "escolas", "creches", "serralharias", "construcao-civil", "engenheiros" ], "type": "string", "description": "Business category to search for. Pick a common category from the list, or choose 'Custom category' and type your own slug below (mode=search).", "default": "restaurantes" }, "customCategory": { "title": "Custom category (overrides selection above)", "type": "string", "description": "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": { "title": "Location (concelho / city)", "enum": [ "", "custom", "lisboa", "porto", "coimbra", "braga", "faro", "aveiro", "setubal", "leiria", "evora", "viseu", "guarda", "beja", "portalegre", "santarem", "castelo-branco", "viana-do-castelo", "vila-real", "braganca", "funchal", "ponta-delgada", "sintra", "cascais", "oeiras", "almada", "amadora", "loures", "gaia", "vila-nova-de-gaia", "matosinhos", "guimaraes", "odivelas", "gondomar", "maia", "barcelos" ], "type": "string", "description": "Portuguese city or concelho to search in. Leave as 'Any location (nationwide)' to search the category across all of Portugal (mode=search).", "default": "" }, "customLocation": { "title": "Custom location (overrides selection above)", "type": "string", "description": "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": { "title": "Sort order", "enum": [ "ranked", "popular" ], "type": "string", "description": "How to order search results (mode=search).", "default": "ranked" }, "openNowOnly": { "title": "Open now only", "type": "boolean", "description": "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.", "default": false }, "minRating": { "title": "Minimum rating", "enum": [ "", "1", "2", "3", "4", "5" ], "type": "string", "description": "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).", "default": "" }, "fetchDetails": { "title": "Fetch full business profiles", "type": "boolean", "description": "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).", "default": true }, "businessUrls": { "title": "Business profile URLs (mode=detail)", "type": "array", "description": "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.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "pai.pt business profile URL." } } }, "default": [] }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Hard cap on the number of business records to return.", "default": 20 } } }, "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 } } } } } } } } } } ```