páginasamarelas.pt APIpáginasamarelas.pt ↗
Access Portuguese business listings from Páginas Amarelas (pai.pt). Search by keyword, browse categories, and retrieve contact details, geo coordinates, and hours.
curl -X GET 'https://api.parse.bot/scraper/c13d65ce-1796-45fb-bd3d-d7db50135285/search_businesses?page=1&query=restaurante&location=Lisboa' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for businesses by keyword and optional location on pai.pt. Returns paginated results with business names, URLs, IDs, and addresses.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search keyword (e.g., 'restaurante', 'hotel') |
| location | string | Location filter (e.g., 'Lisboa', 'Porto'). Omitting returns results across all of Portugal. |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"query": "string, the search keyword used",
"location": "string or null, the location filter used",
"businesses": "array of objects with keys: url, name, id, slug, category, address",
"total_results": "integer, total number of results found"
},
"sample": {
"data": {
"page": 1,
"query": "restaurante",
"location": "Lisboa",
"businesses": [
{
"id": "4132",
"url": "https://www.pai.pt/paginas/4132-restaurante-bar-caldeiras-vulcoes",
"name": "Restaurante-Bar Caldeiras & Vulcões",
"slug": "restaurante-bar-caldeiras-vulcoes",
"address": "4435-665 BAGUIM DO MONTE",
"category": "restaurantes"
}
],
"total_results": 500
},
"status": "success"
}
}About the páginasamarelas.pt API
This API provides structured access to Páginas Amarelas Portugal (pai.pt) through 5 endpoints covering search, category browsing, and full business detail retrieval. The search_businesses endpoint returns paginated results including names, addresses, and IDs for businesses matching a keyword and optional location. Detail endpoints expose up to 10 fields per listing: phone, address, website, geo coordinates, logo, image, categories, and description.
Search and Discovery
The search_businesses endpoint accepts a required query string and an optional location filter (e.g., 'Lisboa', 'Porto'). Omitting location returns results across all of Portugal. The response includes a businesses array with each entry carrying a url, name, id, slug, category, and address, plus a total_results count and the current page number for pagination. Combine this with browse_category and the category slug values from list_categories to navigate the directory hierarchy without needing a keyword.
Business Detail Retrieval
Two endpoints expose full business records. get_business_detail takes the full detail page url (e.g., https://www.pai.pt/paginas/4132-...), while get_business_by_id accepts the numeric id available from search results. Both return identical response shapes: name, phone, address, website, description, logo, image, categories (array of strings), and a geo object with latitude and longitude. If a field is not populated on the source listing, it will return null.
Category Browsing
list_categories requires no inputs and returns the top-level directory taxonomy: each entry includes a name, slug, url, and result_count. Passing one of those slugs to browse_category either returns a sub_categories array (for parent nodes) or a businesses array (for leaf categories). The optional location parameter narrows results geographically, and page handles pagination at both levels.
- Build a local business finder for Portugal filtered by city using
search_businesseswith thelocationparameter - Geocode Portuguese business addresses by pulling
geo.latitudeandgeo.longitudefromget_business_detail - Generate a lead list of businesses in a sector by iterating
browse_categoryacross a leaf-level category slug - Enrich a CRM with phone numbers and websites by calling
get_business_by_idfor each known business ID - Map the full category taxonomy of pai.pt by recursively resolving slugs through
list_categoriesandbrowse_category - Monitor new business listings in a specific category by paginating
browse_categoryon a schedule - Cross-reference business descriptions and categories to classify Portuguese SMEs by vertical
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Páginas Amarelas (pai.pt) offer an official developer API?+
What does `browse_category` return, and how does its response differ between parent and leaf categories?+
'comer-beber'), the response populates the sub_categories array with name, slug, and url entries and returns an empty businesses array. For leaf categories (e.g., 'restaurantes'), businesses is populated and sub_categories is empty. Use list_categories first to get valid top-level slugs.Are opening hours returned by any endpoint?+
get_business_detail or get_business_by_id. Those endpoints cover contact information, geo coordinates, categories, description, logo, and image. You can fork this API on Parse and revise it to add an opening hours field if that data is present on the source listing pages.Can I retrieve user reviews or ratings for a business?+
Does the `search_businesses` endpoint cover the entire country, or only specific regions?+
location parameter returns results across all of Portugal. Providing a location string (e.g., 'Porto') narrows results to that area. Coverage depends on what businesses are listed on pai.pt; the API does not add listings beyond what the directory contains.