Pingo Doce APIpingodoce.pt ↗
Access Pingo Doce product data, current promotions, store locations, recipes, and digital leaflets via 7 structured API endpoints.
What is the Pingo Doce API?
The Pingo Doce API covers 7 endpoints that expose product catalog data, live promotions, store locations, digital leaflets, and recipes from Portugal's Pingo Doce supermarket chain. The search_products endpoint accepts a keyword query and returns product objects including price, brand, discount, and category. The get_product_details endpoint goes further, adding nutritional data, country of origin, and a full product description for individual items.
curl -X GET 'https://api.parse.bot/scraper/dfc0c785-3e6b-4512-92f8-2e52c1ca6c74/get_promotions?limit=12&start=0&category_id=ec_promos_1100000' \ -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 pingodoce-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.
"""Pingo Doce SDK — browse promotions, search products, find stores."""
from parse_apis.pingo_doce_api import PingoDoce, ProductNotFound
client = PingoDoce()
# Browse current promotions — limit caps total items fetched.
for product in client.products.promotions(limit=3):
print(product.name, product.price, product.promo_label)
# Search for milk products, take the first result and drill into details.
milk = client.products.search(query="leite", limit=1).first()
if milk:
print(milk.name, milk.brand, milk.price)
# Fetch full product details including nutrition info.
try:
detail = client.productdetails.get(url=milk.url)
print(detail.name, detail.current_price, detail.unit)
for entry in detail.nutrition[:3]:
print(entry.name, entry.value)
except ProductNotFound as exc:
print(f"Product gone: {exc.url}")
# Find nearby stores in Lisbon.
store = client.stores.find(lat=38.7071, lng=-9.13549, radius=5000, limit=1).first()
if store:
print(store.name, store.city, store.store_hours)
# Search recipes for chicken dishes.
for recipe in client.recipes.search(query="frango", limit=3):
print(recipe.title, recipe.url)
print("exercised: products.promotions / products.search / productdetails.get / stores.find / recipes.search")
Fetch current promotional products from the store catalog. Returns paginated results of products currently on promotion. Pagination is offset-based via the start parameter.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of products to return per page. |
| start | integer | Offset for pagination (0-based index of the first result). |
| category_id | string | Category ID for promotions filtering. |
{
"type": "object",
"fields": {
"count": "integer, number of products returned",
"products": "array of promotional product objects"
},
"sample": {
"data": {
"count": 12,
"products": [
{
"id": "544184",
"url": "https://www.pingodoce.pt/home/produtos/talho/aves/frango/bife%2Fpeito-de-frango-embalado-nosso-talho-544184.html",
"name": "Bife/Peito de Frango Embalado",
"unit": "0.5 Kg",
"brand": "Nosso Talho",
"image": "https://www.pingodoce.pt/dw/image/v2/BLJJ_PRD/on/demandware.static/-/Sites-pingo-doce-master/default/dwa8c02627/images/medium/544184_b35a81450dae22cf2c57f83fa6d0d563.jpg?sw=198",
"price": 6.19,
"category": "Frango",
"discount": null,
"promo_label": "Apenas",
"original_price": 6.49
}
]
},
"status": "success"
}
}About the Pingo Doce API
Product Catalog and Promotions
The search_products endpoint takes a query string (e.g. 'leite' or 'azeite') plus optional limit and start parameters for pagination. It returns an array of product objects, each carrying id, name, brand, price, original_price, discount, promo_label, unit, category, image, and url. The get_promotions endpoint returns the same product shape but scoped to currently promoted items; it also accepts an optional category_id to narrow results to a specific department.
Product Detail and Categories
get_product_details accepts a full product url and returns richer fields: current_price, original_price, description, origin (country of origin when the source carries it), and a nutrition array of {name, value} pairs for products that include nutritional data. Fields like origin and nutrition are null or empty when the source does not list them for a given product. get_product_categories requires no inputs and returns every top-level category with its name, url, and cgid identifier, which can then feed the category_id filter in get_promotions.
Stores, Leaflets, and Recipes
get_stores locates physical Pingo Doce stores using lat, lng, and radius (in meters). Each store object in the response includes id, name, address1, city, postalCode, latitude, longitude, services, and structured storeHours. get_folhetos returns the current promotional leaflets and catalogs as an array of objects with title, url, and image—no parameters needed. get_receitas fetches recipes, with an optional query parameter to filter by keyword; each recipe object contains title, url, and image.
The Pingo Doce API is a managed, monitored endpoint for pingodoce.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when pingodoce.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 pingodoce.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?+
- Monitor price changes and discount depth on specific products using
original_priceanddiscountfields fromsearch_products. - Build a Portuguese grocery price comparison tool by querying product categories and paginating through
get_promotions. - Display a store locator map by feeding coordinates into
get_storesand rendering the returnedlatitude,longitude, andstoreHours. - Aggregate weekly deal sheets by fetching
get_folhetoson a schedule and tracking new or changed leaflet URLs. - Generate meal-planning content by combining
get_receitasrecipe results with matching product searches. - Track nutritional information for a product set using the
nutritionarray returned byget_product_details. - Feed a category-browsing UI by using
cgidvalues fromget_product_categoriesas filters in subsequent promotion queries.
| 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 Pingo Doce offer an official public developer API?+
What does `get_product_details` return that the search and promotions endpoints do not?+
get_product_details returns description, origin (country of origin), and a nutrition array of name-value pairs. These fields are absent from search_products and get_promotions, which return catalog-level data. Note that origin and nutrition are null or empty for products where Pingo Doce does not list that information.How does pagination work across the catalog endpoints?+
search_products and get_promotions both support limit (results per page) and start (zero-based offset) parameters. The response includes a count field indicating how many results were returned in the current page, not the total catalog size. You increment start by limit to walk through pages.Does the API return product reviews or customer ratings?+
Are recipe details like ingredient lists or step-by-step instructions included in `get_receitas`?+
get_receitas endpoint returns title, url, and image for each recipe—full ingredient lists and preparation steps are not included in the response. You can fork this API on Parse and revise it to build a recipe detail endpoint using the returned url.