Gazetkowo APIgazetkowo.pl ↗
Access promotional products, retail leaflets, and store data from Gazetkowo.pl via 6 endpoints. Search products by keyword, browse flyers, and filter by retailer.
What is the Gazetkowo API?
The Gazetkowo.pl API exposes 6 endpoints for accessing promotional flyer data from Poland's major retailers. Using search_products, you can query promotional items by keyword and receive structured results including price, old_price, validity dates, retailer identity, and product slugs. The API also covers leaflet browsing, store listings, and individual product detail retrieval — all scoped to active or current promotional periods.
curl -X GET 'https://api.parse.bot/scraper/8113a919-68fd-4a8f-83ab-ae0980d250ec/search_products?query=mleko&postcode=00-001&sort_by_price=True' \ -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 gazetkowo-pl-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.
"""Gazetkowo SDK — browse Polish promotional leaflets, search product deals, explore stores."""
from parse_apis.gazetkowo_api import Gazetkowo, ProductNotFound
client = Gazetkowo()
# Search for milk products sorted by price — find the cheapest deals.
for product in client.products.search(query="mleko", sort_by_price=True, limit=5):
print(product.name, product.price, product.retailer.name)
# List all retailers with active offers.
retailer = client.retailers.list(limit=1).first()
if retailer:
print(retailer.name, retailer.slug, retailer.newspapers_count)
# Browse the retailer's current leaflets.
for leaflet in retailer.leaflets(limit=3):
print(leaflet.custom_name, leaflet.start_at, leaflet.end_at)
# Browse the latest leaflets across all stores.
for leaflet in client.leaflets.latest(per_page=5, limit=3):
print(leaflet.custom_name, leaflet.retailer.name, leaflet.newspaper_current_order)
# Typed error handling: attempt to get a product that may have expired.
try:
detail = client.products.search(query="mleko", limit=1).first()
if detail:
print(detail.name, detail.slug)
except ProductNotFound as exc:
print(f"Product expired or not found: {exc.slug}")
print("exercised: products.search / retailers.list / retailer.leaflets / leaflets.latest")
Full-text search over promotional products by keyword. Returns matching products with price, retailer, and validity dates. Client-side sort by price ascending is available. Pagination is not supported — the full result set is returned in one response.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword for promotional products (e.g. 'mleko', 'chleb', 'piwo') |
| postcode | string | Polish postal code for location scoping (format: XX-XXX) |
| sort_by_price | boolean | Sort results by price ascending |
{
"type": "object",
"fields": {
"total": "integer total number of products returned",
"products": "array of product objects with id, name, price, old_price, start_date, end_date, image_url, retailer, newspaper_id, and slug"
},
"sample": {
"data": {
"total": 92,
"products": [
{
"id": "019e79d8-3685-71e8-8f18-4ef850f2fe4a",
"name": "Mleko zsiadłe Mlekovita",
"slug": "mleko-zsiadle-mlekovita-2y12kx1d7yjwmscli0q52fgy6of4jocsi2vtjdfmfdubgk5ksbfcuww",
"price": 2.59,
"end_date": "2026-06-13 23:59:59",
"retailer": {
"id": "4d89319f-c94e-46ce-b0ad-74f18f45e78c",
"name": "E.Leclerc",
"slug": "eleclerc"
},
"image_url": "https://cdn1.promotons.com/resize?fileName=production/gazetkowo/newspapers/019e776a-31bd-72b1-aa3b-d4088a120613/hiperComPage7037163.jpeg",
"old_price": null,
"start_date": "2026-06-02 00:00:00",
"newspaper_id": "019e776a-1fab-737b-8c2c-a9041d820180"
}
]
},
"status": "success"
}
}About the Gazetkowo API
Product Search and Detail
The search_products endpoint accepts a query string (e.g. 'mleko', 'chleb') and returns an array of matching promotional products. Each product object includes id, name, price, old_price, start_date, end_date, image_url, slug, and a nested retailer object. You can optionally pass a postcode (format XX-XXX) to scope results geographically, and set sort_by_price to true to order results by ascending price. For full detail on a single item, get_product_detail accepts a slug (either the origin slug or the full slug from search results) plus a retailer_id UUID and returns the newspaperProduct object with fields like originSlug, oldPrice, startAt, endAt, and imageUrl. Note: expired products return a not-found error rather than stale data.
Store and Leaflet Access
list_stores returns all retailers with active promotional offers. Each retailer object includes a UUID id, slug, retailerCategoryId, newspapersCount, and currentlyActiveNewspapersIds — which is the primary input surface for downstream leaflet calls. get_store_leaflets takes a retailer_id and returns the newspapersWithoutSubcategory object, whose elements array contains leaflets with id, customName, startAt, endAt, newspaperCurrentOrder, coverImage, images, and retailer context.
Leaflet Detail and Latest Listings
get_leaflet_detail accepts an order value (the newspaperCurrentOrder field from get_store_leaflets) and a retailer_slug (e.g. 'lidl', 'biedronka', 'kaufland'). It returns the full newspaper object including all page images as an array, plus tagsWithCategory and tagsWithoutCategory arrays that group products tagged in the leaflet. get_latest_leaflets lists recent leaflets across all retailers with pagination via page and per_page parameters, and supports filtering by retailer_category_id — a UUID drawn from the retailerCategoryId field in list_stores results.
The Gazetkowo API is a managed, monitored endpoint for gazetkowo.pl — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when gazetkowo.pl 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 gazetkowo.pl 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?+
- Track price drops on grocery items by comparing
priceandold_pricefields fromsearch_productsacross polling intervals. - Build a leaflet browser for Polish retail chains by paginating
get_latest_leafletsand renderingcoverImagethumbnails. - Aggregate current promotional product availability by retailer using
list_storesandget_store_leafletstogether. - Filter promotional flyers by store category (e.g. supermarkets vs. electronics) using
retailer_category_idinget_latest_leaflets. - Retrieve all page images from a specific leaflet using
get_leaflet_detailwithorderandretailer_sluginputs. - Monitor product validity windows by reading
start_dateandend_datefromsearch_productsto detect expiring deals. - Build a postcode-aware product search tool using the
postcodeparameter insearch_productsto scope results by location.
| 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 Gazetkowo.pl have an official developer API?+
What does `get_product_detail` return, and what happens with expired products?+
get_product_detail returns a newspaperProduct object with fields including id, name, slug, originSlug, price, oldPrice, imageUrl, retailer, startAt, and endAt. Products that are past their promotion end date return a not-found error rather than a result with stale pricing data, so results can be treated as current.Can I filter `search_products` results by retailer or category?+
search_products endpoint supports filtering by postcode and sorting by price, but does not currently expose a retailer or category filter parameter. The retailer object in each result includes id and slug fields, so client-side filtering by retailer is straightforward. You can fork this API on Parse and revise it to add a server-side retailer filter if needed.Does the API expose historical promotional data or only current offers?+
get_product_detail, and list_stores returns retailers with active offers. Historical pricing trends or archival leaflets are not covered. You can fork this API on Parse and revise it to add an archival endpoint if the underlying data becomes available.How does leaflet pagination work in `get_latest_leaflets`?+
get_latest_leaflets accepts page (page number) and per_page (results per page) as optional integer inputs. Results are nested under newspapers.elements, where each element includes id, customName, startAt, endAt, coverImage, retailer, and retailerCategory. Filtering by store type is possible via the retailer_category_id parameter, which accepts a UUID from the retailerCategoryId field in list_stores results.