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

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

Example: lawyers nationwide, most popular first

{
  "mode": "search",
  "category": "advogados",
  "location": "",
  "sortBy": "popular",
  "maxItems": 50
}

Example: 4+ star veterinarians in Porto, open right now

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

Example: fast name-only scan (no detail-page enrichment)

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

Example: fetch specific business profiles

{
  "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/<location> 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).