Com APIgandalf.com.pl ↗
Access discounted book, game, and stationery deals from Gandalf.com.pl. Retrieve deal categories, paginated product listings, and store-wide best-deal rankings.
What is the Com API?
The Gandalf.com.pl API exposes 3 endpoints covering promotional, clearance, and outlet sections of Poland's Gandalf online bookstore. Use list_deal_categories to discover active deal sections, list_deals to paginate through up to 28 discounted products per page with current price, regular price, discount percentage, and 30-day lowest price, and list_best_deals to retrieve a ranked cross-section of the top deals store-wide.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/54058672-4a29-4de7-bdc2-c0bcf648b3d9/list_deal_categories' \ -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 gandalf-com-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.
"""Walkthrough: Gandalf.com.pl Deals SDK — browse promotional sections and their discounted products."""
from parse_apis.gandalf_com_pl_api import Gandalf, Sort, CategoryNotFound
client = Gandalf()
# Browse the store-wide best deals ranking.
for deal in client.best_deals.list(top=5, limit=5):
print(deal.rank, deal.title, deal.price, deal.savings_percent)
print(f" section: {deal.section_name}")
# List all current deal sections across the store.
for cat in client.categories.list(limit=5):
print(cat.name, cat.department, cat.category_id)
# Pick the first category and browse its cheapest deals.
cat = client.categories.list(limit=1).first()
if cat is not None:
for deal in cat.deals.list(sort=Sort.PRICE_ASC, limit=3):
print(deal.title, deal.price, deal.currency)
if deal.regular_price is not None:
print(f" was {deal.regular_price}")
# Point-construct a known category to list deals without fetching it first.
try:
toys = client.category(category_id="2003_12407")
for deal in toys.deals.list(sort=Sort.POPULARITY, limit=3):
print(deal.title, deal.brand, deal.authors)
except CategoryNotFound:
print("Category no longer available")
print("exercised: best_deals.list / categories.list / category() / deals.list")
Returns the deal sections currently linked from the store's main category menu: promotional, clearance ('wyprzedaż') and outlet sections across departments (books, textbooks, games & toys, stationery, music). One round trip. Each row carries the category_id accepted by list_deals; the set changes as the store runs new campaigns, so re-read it rather than caching ids. A section may be temporarily empty (e.g. the store-wide outlet).
No input parameters required.
{
"type": "object",
"fields": {
"count": "number of sections returned",
"categories": "array of deal sections; each has category_id (opaque id for list_deals), name (site label, Polish), department (parent department label or null for store-wide sections), url (public page)"
},
"sample": {
"data": {
"count": 10,
"categories": [
{
"url": "https://www.gandalf.com.pl/gry-zabawki-promocja-c-2003_12407.html",
"name": "Promocja",
"department": "Gry / Zabawki",
"category_id": "2003_12407"
},
{
"url": "https://www.gandalf.com.pl/outlet",
"name": "Outlet",
"department": null,
"category_id": "outlet"
}
]
},
"status": "success"
}
}About the Com API
Deal Categories and Sections
list_deal_categories returns all deal sections currently linked from the store's main category menu — promotional, clearance (wyprzedaż), and outlet sections across departments including books, textbooks, games and toys, stationery, and music. Each entry includes a category_id (used directly as the required input to list_deals), a Polish-language name label, and a department field indicating the parent category. No parameters are required.
Paginated Deal Listings
list_deals accepts a required category_id (exactly as returned by list_deal_categories) and optional page (1-based) and sort parameters. Each response returns up to 28 products with fields including product_id, title, brand, authors, ean, category_path (the site breadcrumb), and pricing fields covering current price, regular price, discount percentage, and 30-day lowest price. The response also carries total_pages, has_more, page, requested_page, and category_name. One important behavior: requesting a page number beyond the last available page returns the store's last page rather than an empty result, so has_more and requested_page vs page should be compared to detect overrun.
Store-Wide Best Deals Ranking
list_best_deals scans the first listing page of every deal section in the store's default order, deduplicates products, ranks by discount, and returns up to 40 results. The limit parameter (1–40, clamped) controls how many ranked items are returned. The response includes candidates_considered (total distinct products evaluated before the limit), sections_scanned (with per-section items_on_first_page and total_pages), and sections_failed (with category_id, name, and reason for any section that could not be read). This endpoint is a single call that replaces manually iterating all categories.
The Com API is a managed, monitored endpoint for gandalf.com.pl — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when gandalf.com.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 gandalf.com.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?+
- Monitor daily price drops on Polish books and textbooks by polling
list_dealsper category and comparingpriceagainstregular_price. - Build a deal-alert bot that checks
list_best_dealsfor products whosediscount_percentageexceeds a threshold. - Track the 30-day lowest price field to verify whether a current deal is the cheapest it has been in the past month.
- Aggregate EAN codes from deal listings to cross-reference Gandalf outlet prices against other Polish bookseller catalogues.
- Generate a ranked clearance report for board games and toys by targeting the games and toys department sections returned by
list_deal_categories. - Detect newly added outlet products by comparing successive
list_dealspages and flaggingproduct_idvalues not seen in a prior snapshot.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Gandalf.com.pl have an official developer API?+
What pricing fields does `list_deals` return for each product?+
list_deals returns four price-related fields per product: the current discounted price, the regular (pre-discount) price, the discount percentage, and the 30-day lowest price. The 30-day lowest price reflects the store's own displayed value and is useful for assessing whether the current deal is a genuine minimum.What happens if I request a page number beyond the last page in `list_deals`?+
requested_page field against the returned page field — if they differ, you have overrun the section. has_more will be false in that case.Does the API cover product detail pages, customer reviews, or stock availability?+
Can `list_best_deals` scan beyond the first page of each section?+
sections_scanned array shows how many total pages each section has, so you can see when a section has deeper inventory. You can fork this API on Parse and revise the endpoint to fetch additional pages per section before ranking.