Páginas Amarelas APIpáginasamarelas.pt ↗
Access Portuguese business listings from pai.pt. Search by keyword and location, browse categories, and retrieve contact details, hours, and coordinates.
What is the Páginas Amarelas API?
This API exposes 5 endpoints covering the pai.pt Portuguese Yellow Pages directory, returning business names, addresses, phone numbers, geo coordinates, opening hours, and category data. Use search_businesses to run keyword searches across all of Portugal or filter by city, and use get_business_detail to pull a full profile including website, logo, description, and latitude/longitude for any listed business.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace p-ginasamarelas-pt-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.paginas_amarelas_portugal_pai_pt_api import PaginasAmarelas, Business, BusinessSummary, Category
client = PaginasAmarelas()
# Search for restaurants in Lisboa
for summary in client.businesses.search(query="restaurante", location="Lisboa", limit=5):
print(summary.name, summary.address)
# Get full details for the first result
detail = summary.details()
print(detail.name, detail.phone, detail.website)
print(detail.opening_hours)
# List all top-level categories
for cat in client.categories.list(limit=5):
print(cat.name, cat.slug, cat.result_count)
# Browse sub-categories of a category
food = client.category(slug="comer-beber")
for sub in food.sub_categories.list(limit=5):
print(sub.name, sub.slug)
# Browse businesses in a leaf category
restaurants = client.category(slug="restaurantes")
for biz in restaurants.browse(location="Porto", limit=3):
print(biz.name, biz.url)
Full-text search over the pai.pt business directory. query matches business names and categories; location narrows geographically. Returns paginated results with business summaries including name, URL, ID, slug, category, and address. Pagination via page parameter. total_results reflects the server's count for the query/location combination.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search keyword (e.g., 'restaurante', 'hotel', 'dentista'). |
| 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 business summary 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 & Vulcoes",
"slug": "restaurante-bar-caldeiras-vulcoes",
"address": "4435-665 BAGUIM DO MONTE",
"category": "restaurantes"
}
],
"total_results": 500
},
"status": "success"
}
}About the Páginas Amarelas API
Search and Browse
The search_businesses endpoint accepts a required query string (e.g., 'dentista', 'hotel') and an optional location filter such as 'Lisboa' or 'Porto'. Results are paginated via the page parameter and each item in the businesses array includes name, address, category, id, slug, and url. The total_results field tells you how many records match before fetching subsequent pages. The browse_category endpoint mirrors this structure but navigates by category slug: top-level slugs like 'comer-beber' return a sub_categories array, while leaf slugs like 'restaurantes' return a businesses array with the same summary fields.
Category Discovery
Before calling browse_category, use list_categories to retrieve all top-level categories from the pai.pt homepage. Each entry exposes name, slug, url, and result_count. Pass a slug directly into browse_category to drill down. The two-level hierarchy (parent → leaf) means a single intermediate call is often needed to reach listable businesses.
Business Detail
Both get_business_detail (takes a full url) and get_business_by_id (takes a numeric id from search results) return the same 10-field profile: name, address, phone, website, description, logo, image, categories (array of tag strings), geo (object with latitude and longitude), and the canonical url. Opening hours are returned by day, making these endpoints useful for time-sensitive queries. The numeric id field surfaced in search_businesses results feeds directly into get_business_by_id, so no URL construction is needed.
The Páginas Amarelas API is a managed, monitored endpoint for páginasamarelas.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when páginasamarelas.pt changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official páginasamarelas.pt API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a local business finder for Portugal using
search_businesseswithlocationfiltering by city - Geocode Portuguese business addresses by extracting
geo.latitudeandgeo.longitudefromget_business_detail - Aggregate contact data (phone, website) for businesses in a specific category using
browse_category+get_business_by_id - Generate a structured category tree for pai.pt by combining
list_categorieswith recursivebrowse_categorycalls - Check opening hours for businesses in a given sector before routing field sales teams across Portuguese cities
- Enrich a CRM with verified Portuguese business profiles by matching names and pulling full detail via
get_business_by_id
| 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 | 100 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 pai.pt (Páginas Amarelas Portugal) have an official developer API?+
What does get_business_detail return beyond what search_businesses shows?+
search_businesses returns summary fields: name, address, category, id, slug, and url. get_business_detail adds phone, website, description, logo, image, a categories array of tag strings, opening hours broken down by day, and a geo object with latitude and longitude. Use the detail endpoint whenever you need contact or location data.Does browse_category always return a list of businesses?+
slug is a top-level category (e.g., 'comer-beber'), the response populates sub_categories instead of businesses. You need to pass one of those sub-category slugs back into browse_category to reach actual business listings. Leaf-level slugs (e.g., 'restaurantes') return the businesses array directly.Does the API cover user reviews or ratings for listed businesses?+
Is pagination supported across all listing endpoints?+
search_businesses and browse_category both accept a page integer parameter. search_businesses also returns total_results so you can compute how many pages exist before iterating. get_business_detail and get_business_by_id operate on a single business and have no pagination parameter.