Albert APIalbert.cz ↗
Access Albert.cz grocery data via 8 endpoints: recipes with ingredients and steps, promotional leaflets with OCR pricing, store locations, and magazine content.
What is the Albert API?
The Albert.cz API exposes 8 endpoints covering the full range of content from the Czech grocery chain's website, including recipe search and detail, promotional leaflet data with OCR-extracted product and price text, store finder with coordinates, and CMS-driven magazine and monthly deals pages. The get_leaflet_detail endpoint is particularly useful for extracting current promotional pricing across Hypermarket and Supermarket formats.
curl -X GET 'https://api.parse.bot/scraper/1959d942-293a-4889-8d0c-9ecdcfdfa36e/search_recipes?page=0&query=smoothie' \ -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 albert-cz-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: Albert.cz SDK — recipes, leaflets, stores."""
from parse_apis.albert_cz_content___leaflets_api import Albert, RecipeNotFound
client = Albert()
# Search recipes and browse results
for recipe in client.recipesummaries.search(query="smoothie", limit=3):
print(recipe.title, recipe.rating, recipe.difficulty_name)
# Drill into one recipe for full details
summary = client.recipesummaries.search(query="kuřecí", limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.servings)
for ing in detail.fractional_recipe_ingredients[:3]:
print(f" {ing.quantity} {ing.measure_unit} {ing.ingredient_name}")
# Typed error handling: try fetching a non-existent recipe
try:
client.recipes.get(id="nonexistent_999")
except RecipeNotFound as exc:
print(f"Recipe not found: {exc.id}")
# List current leaflets and show validity dates
for leaflet in client.leaflets.list_current(limit=2):
print(leaflet.title, leaflet.validity_start_date, leaflet.validity_end_date)
# Find stores in Praha
for store in client.stores.search(query="Praha", limit=3):
print(store.id, store.grocery_store_type, store.geo_point.latitude, store.geo_point.longitude)
print("exercised: recipesummaries.search / details / recipes.get / leaflets.list_current / stores.search")
Search for recipes by keyword with optional pagination. Returns paginated results with recipe IDs, titles, ratings, difficulty, preparation time, and image URLs.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-indexed) |
| query | string | Search keyword (e.g. 'smoothie', 'kuřecí', 'salát') |
{
"type": "object",
"fields": {
"facets": "array of available filter facets",
"results": "array of recipe summaries with id, title, rating, difficultyName, preparationTimeName",
"pagination": "object with currentPage, totalResults, totalPages, pageSize"
},
"sample": {
"data": {
"facets": [
{
"code": "preparationTimeEnumValue",
"name": "Doba přípravy",
"values": [
{
"code": "LESSTHANEQUALS15",
"name": "0-15 minut",
"count": 42
}
]
}
],
"results": [
{
"id": "a1938",
"title": "Kiwimangové Smoothie",
"rating": "4/5",
"difficultyName": "Velmi snadné",
"preparationTimeName": "16-30 minut"
}
],
"pagination": {
"pageSize": 12,
"totalPages": 5,
"currentPage": 0,
"totalResults": 52
}
},
"status": "success"
}
}About the Albert API
Recipes
The search_recipes endpoint accepts a query string (e.g. 'kuřecí', 'salát') and an optional zero-indexed page parameter, returning recipe summaries with id, title, rating, difficultyName, and preparationTimeName alongside pagination metadata (currentPage, totalResults, totalPages). Pass the returned id to get_recipe_detail to retrieve full data: step-by-step recipeCookingSteps, a fractionalRecipeIngredients array with ingredientName, quantity, and measureUnit, nutrition info, and serving count. Use list_recipe_categories to enumerate available filter facets — preparation time, difficulty, and special diet — each with a count field indicating how many recipes match.
Promotional Leaflets
get_current_leaflets returns active promotional leaflets split into hypermarket and supermarket arrays. Each leaflet object includes validityStartDateFormatted, validityEndDateFormatted, imageUrl, and a viewUrl from which the leaflet slug (the final path segment) can be extracted. Pass that slug to get_leaflet_detail to retrieve all pages of the leaflet as spread objects, each containing page-level imageUrl values and OCR-extracted text — the primary way to access product names and prices from the printed leaflet without parsing images manually.
Store Locations
find_stores operates in two modes depending on whether a query is provided. With a query such as 'Praha' or 'Brno', it returns full store detail: address, description, groceryStoreType, storeServices, and a geoPoint with coordinates. Without a query, it returns map-pin data for all stores. The response also includes facets for filtering by store type and available services, plus standard pagination fields.
Magazine and Monthly Deals
get_magazine_articles and get_monthly_deals both return CMS page objects containing structured content keyed by component IDs. The page object includes text components, image banners, and recipe carousels as they appear on the Albert Magazine and Hit měsíce (monthly deals) sections of the site. These responses reflect the current published state of those pages and are not parameterized — there are no filters or date inputs.
The Albert API is a managed, monitored endpoint for albert.cz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when albert.cz 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 albert.cz 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 Czech recipe search tool filtered by difficulty and preparation time using
search_recipesfacets - Extract weekly promotional product prices from Albert leaflets via OCR text in
get_leaflet_detailspreads - Map all Albert Hypermarket and Supermarket locations with
find_storescoordinate data - Compare current Hypermarket vs Supermarket promotions using the split structure from
get_current_leaflets - Aggregate ingredient lists and serving sizes from
get_recipe_detailfor meal planning applications - Monitor monthly deal content changes with
get_monthly_dealsCMS component data - Identify stores with specific services (e.g. pharmacy, bakery) by filtering
storeServicesfromfind_stores
| 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 Albert.cz have an official public developer API?+
How do I get product prices from a promotional leaflet?+
get_current_leaflets to retrieve active leaflets and their viewUrl fields. Extract the slug from the end of the viewUrl path, then pass it as the id parameter to get_leaflet_detail. Each page in the response includes OCR-extracted text alongside its image URL, which is where product names and prices appear.Can I retrieve historical or archived leaflets from previous weeks?+
get_current_leaflets only returns leaflets that are currently valid, identified by their validityStartDateFormatted and validityEndDateFormatted fields. Past leaflets are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting archived leaflet slugs if you have access to those identifiers.Does `search_recipes` support filtering by diet type or ingredient?+
search_recipes accepts a query keyword and a page number. It returns filter facets (including special diet options) in the response, but those facet codes are not currently accepted as direct input parameters for server-side filtering. You can fork this API on Parse and revise it to pass facet codes as query inputs if the underlying source supports it.What store detail is returned when no query is passed to `find_stores`?+
query, find_stores returns map-pin data for all Albert stores — primarily geoPoint coordinates and basic store identifiers. Passing a location query like 'Praha' returns richer objects that include address, description, groceryStoreType, and the full storeServices array.