generated api¶

return whether this store's client declares capability.

close the http connection pool.

return one page of summaries; pass next_cursor back to continue.

return a complete product record by store id.

return the root of the storefront category tree.

return one category with its children and listed products.

yield summaries for query across every page.

return every catalog summary once, keyed on product id.

stream an image to destination through an atomic replacement.

resolve a postal code to a store binding and return a client.

return the stores or zones the storefront can be bound to.

yield every catalog summary, possibly with duplicates.

return a complete product record by its ean.

return the products the storefront presents as new.

return the products currently on offer.

return the ordered sections of the storefront home page.

resolve a postal code with one request and return a scoped client.

search one page of product summaries.

the cursor is the zero-based page number as a string; None requests the first page.

return a complete product record by id.

return the storefront category tree.

return one category with its groups and their products.

only the second level has a category page: a top-level id answers http 404 there. on that 404 the category tree is fetched, one more request, and a root found in it is returned as the tree spells it, with its second-level categories as children and no products. an id the tree does not hold as a root, such as one of the groups below a second-level category, raises :class:~supermercapy.NotFoundError.

resolve postal_code to its warehouse and return it as a store.

yield summaries from the category tree and each listed group.

collect deduplicated summaries from all listed category groups.

return the current new-arrival product summaries.

return ordered storefront home sections.

return one seasonal product collection by id.

collect the complete algolia index through top-category partitions.

an index that exposes no category facets is partitioned by score ranges instead: numeric filters work on every index, and a range that reports more hits than the result cap is halved until it fits. records without a score, or more tied scores than the cap, leave the result unreconciled rather than silently short.

download a photo at an optional size through an atomic replacement.

resolve a postal code with one request and return a scoped client.

the first area the storefront lists for the postal code wins; use :meth:list_stores when a postal code maps to more than one.

search one page of products.

the cursor is the next offset as a string; None starts at zero.

return one product by its code.

return the whole category tree, already nested, in one request.

return one category from the tree, with its first page of products.

the tree carries no products, so this costs one request for the tree and one for the listing.

return the areas serving postal_code for one delivery method.

yield the whole catalog by walking offsets a hundred rows at a time.

return one product by its ean, in a single request.

return every product the storefront flags as new, newest first.

the listing is walked a hundred rows per request until it ends.

return every product carrying an immediate discount.

the listing is walked a hundred rows per request until it ends, which was eleven requests for a thousand offers in october 2026. include_deferred widens the result to products that credit money back instead of cutting the shelf price.

list one page of a category, descendants included.

return several products in one request, in the order given.

codes the selected zone does not carry are omitted from the result rather than raising, so compare what comes back against what you asked for.

return the promotional campaigns and their nested subgroups.

list one page of a campaign, selected by its :class:ConsumGroup code.

return the sort orders the storefront currently advertises.

return spelling completions for a partial query.

return the refinement tags the search box offers for a query.

download one image at a rendition through an atomic replacement.

resolve a postal code with one request and return a scoped client.

plusfresc delivers around lleida, barcelona, and tarragona only; a postcode outside that footprint is answered with an http 409 and raises :class:~supermercapy.OutOfCoverageError.

search one page of products.

the backend takes no paging parameter of any kind and answers with at most a hundred rows, so every page is carved out of one response and the cursor is an offset into rows already fetched. a page whose truncated flag is set sat at the cap, which means total_hits is a floor rather than a total and the rest of the matches cannot be reached; walk the category tree instead when you need them all.

the query travels as a path segment, so the characters the backend cannot route there (/ \ % & : * ? < > +) are sent as spaces and trailing dots are dropped; query on the result keeps the original.

return one product by its six-digit item id.

the composite placement id a listing row calls id is not accepted upstream and raises :class:~supermercapy.NotFoundError.

return the whole category tree, already nested, in one request.

return one category with its direct children and a page of products.

the tree carries no products, so this costs one request for the node and one for its listing. the node endpoint names no parent, so parent_id is None here; :meth:get_categories sets it.

yield the whole catalogue from the one listing of the Root node.

the backend answers with every product of the center in a single uncached response of several megabytes, so this costs one request and no token. a product placed under more than one category comes back once per placement; :meth:get_catalog deduplicates by id. gate repeated walks behind :meth:get_catalog_version.

return every store and locker, or only those of one postcode's center.

a locker is listed under the center that prepares its orders, so every id here can be passed straight back to the constructor.

return the products the storefront collects under "novetats".

no row carries a novelty flag of its own, so membership of that category is what marks a product new here.

return the products of the web-offers category.

highlighted swaps it for the smaller carousel of featured campaigns the storefront promotes on its home page.

list one page of a category, descendants included.

the endpoint answers with the whole category at once and takes no paging parameter, so the page is carved out client-side just as it is for search. Root is the whole catalogue, which is several megabytes; gate it behind :meth:get_catalog_version.

return the eight preparation centers, without their lockers.

return the date the catalogue last changed.

the storefront caches its whole tree until this date moves, and so can a caller: nothing else here is cacheable, every listing is served uncached and the catalogue root alone is several megabytes.

return the unit-of-measure codes a product's unit_measure uses.

download one image at a rendition through an atomic replacement.

return one page of hits, sliced from the whole result set.

the storefront takes no page, size or sort parameter and answers every query with all of its hits at once, so a cursor walk re-requests the same response; :meth:iter_search streams it in one request instead.

yield every hit for query from the single response search returns.

page_size is validated and then ignored: there are no pages to fetch, so streaming never issues a second request.

return one article, in either the 13*5361 or 13_5361 spelling.

an unknown id is answered with {"article": null} and http 200 rather than a 404, which becomes a :class:NotFoundError here.

return the whole category tree, already nested, in one request.

every listing response embeds the tree, so asking for a blank listing is the cheapest way to fetch it.

return one category with its children and every article it lists.

one request answers both, because a listing response carries the whole tree alongside its articles. a menu-level category resolves to a node with children and no products: only the level the tree calls a listing level returns articles.

an unknown reference makes the storefront throw, and it answers with an http 500 error page rather than a 404. that page is not retried, and the id is checked against the tree with one more request before it is reported as :class:NotFoundError; an id the tree does know re-raises the original error.

yield every article by walking one listing per branch of the tree.

one request fetches the tree and one more follows for each listing node, which is 493 of them at the time of writing. articles listed under more than one category are yielded more than once; :meth:get_catalog deduplicates them by id.

return the articles badged as new, deduplicated by id.

bonàrea publishes no novelties endpoint, so this filters listings on the :attr:Characteristic.NEW badge. one category costs one request; passing none walks the whole catalog.

return the articles badged as reduced, deduplicated by id.

the badge is the only price-drop signal bonàrea publishes: no previous price accompanies it. the cost is the same as :meth:new_products.

return the postal codes bonàrea delivers to inside one province.

province is the two-digit spanish province code, and town narrows the answer to one town. this is delivery coverage only: it selects nothing, because the catalogue and its prices are national.

return the storefront's pre-rendered product modal as raw html.

:meth:get_product is the structured route; this is the fallback for anything the json omits but the modal renders.

download one image, optionally resized by the cdn, atomically.

omitting both dimensions downloads the original upload; the storefront itself asks for 500 px in a grid and 1000 px on a product page.

bind the sale point that serves postal_code.

carrefour publishes no postcode-to-sale-point resolver: the postcode endpoint answers with physical shops, whose ids belong to a different namespace, and the storefront picks a sale point by mutating session state. so this costs two requests — the shops near the postcode, then the drive directory — and binds the sale point in the same postcode if there is one, otherwise the one nearest the closest shop.

a postcode carrefour does not serve raises :class:~supermercapy.OutOfCoverageError.

search one page of products on the direct index.

the query is lowercased before it is sent, as carrefour's own client does, so both share the cdn's cache key. sort takes the index's own spelling — "price asc", "best_sellers_food desc" — and an unsortable field is refused upstream rather than ignored.

one query reaches at most 2,998 documents: the offset ceiling is 2,498 and a page at most 500 rows. a page whose truncated flag is set sat against that ceiling with matches left over.

return one complete product, nutrition included, from its page.

ids come in four unrelated spellings and are opaque strings, never integers. the slug in a product url is not load-bearing: this asks for a placeholder one and follows the redirect carrefour answers with, which is also how an unknown id is detected — it redirects to the home page instead of to a product.

return one complete product by its barcode.

the index has no barcode endpoint; a barcode is matched as ordinary free text, which returns exactly one document when it is known. the document is then fetched again as a page, because nutrition lives nowhere else, and the barcode is checked against it so a fuzzy text match cannot answer with the wrong product.

return the food departments from the storefront's navigation menu.

one request returns the ten departments, named in the client's language. deep=True adds each department's aisles at one more request per department. the menu stops at the aisles; the leaves under an aisle are the children :meth:get_category returns for it. the menu answers without a warm session, so neither costs the warm-up page unless cloudflare challenges the first request.

return one category with its children and one page of its products.

everything comes from the category's listing page, which answers any placeholder slug, so this costs one page fetch. the page is fixed at 24 products and floors offset to a multiple of 24; the page size cannot be set from the url at all. an unknown id redirects to the home page, which raises :class:~supermercapy.NotFoundError.

return the sale points, or the physical shops near one postcode.

without a postcode this is the drive directory, and every id in it can be passed straight back to the constructor. with one it is the shops near that postcode, ordered by distance; those ids identify buildings rather than sale points and the constructor does not accept them.

return the product carousels of the supermarket home page.

the page is a cms page whose carousels arrive already filled, in page order, with their titles in the cms documents beside them. it is also the warm-up page, so a cold client fetches it twice.

return one rendered page of a category listing by its url.

the url comes from a :class:CarrefourCategory. sponsored rows are dropped: the ad-injected carousels are never read and a card carrying an ad id inside the grid is flagged is_sponsored.

return how many units of a product the session's sale point holds.

stock is published by carrefour's own proxied search and by nothing else. that proxy ignores store, so this figure belongs to the session's default sale point rather than to :attr:sale_point; the two agree only when the session already sits on that sale point.

the proxy also refuses a request without a session parameter with a firewall block rather than an api error, so one is always sent; its value is never read.

return the query completions the search box would offer.

download one image, optionally re-rendered at width pixels.

bind the offer region and price zone of the nearest store.

the stores api has no postal-code filter, so this pages the whole spanish store list once and matches on it: a store in the same postal code first, then the first store of the same province. a postal code with neither raises :class:~supermercapy.OutOfCoverageError.

search one page of both assortments.

the cursor is the next offset as a string; None starts at zero. family narrows the page to one assortment, defaulting to the client's own filter. the search index holds groceries, but only for real keyword queries.

return one product, by either its parent or its variant id.

the detail endpoint accepts parent ids only, so a variant id — the parent plus three digits — is normalised before the request.

return the roots of the shop category tree, read from one facet.

there is no category endpoint: /q/api/category is routed but answers http 404 for spain, so the roots come from the category facet of an empty listing. that facet does not expand them, so their children are empty; :meth:get_category returns one level more. grocery items are not in the tree — their taxonomy is :attr:LidlProduct.category_path.

return one shop category at any depth, its children, and a page.

return every spanish store, or the ones in one postal code.

the api pages two hundred and fifty stores at a time and takes no postal-code filter, so a postal code is matched on the full list.

yield every catalogued product, hydrating one sitemap id at a time.

the sitemap holds about six thousand shop ids and six hundred grocery ids, and each one costs a request, so pass family — or bind one on the client — to walk half of it. ids the storefront has already retired are skipped rather than raising.

return one week's grocery campaign in a single request.

week names one of the campaign pages lidl publishes: current, next, weekend, weekend_next, permanent_cuts, or other_brands. next week's page prices its products through :attr:LidlProduct.future_prices rather than :attr:~supermercapy.Product.price, and from sunday so does the current page, which already lists the week that starts on monday.

return the products of any /c/<slug>/a<id> campaign page.

campaign listings have no json endpoint, so the page is fetched as html and each tile's data-grid-data attribute — the same gridbox a search hit carries — is parsed out of it. the pages are half a megabyte and more, so cache what comes back.

yield the product ids of the sitemap, one request for all of them.

the leading digits split the two assortments — 10 is the online shop, 11 the in-store grocery range — so a family is filtered without fetching anything.

return the leaflets on offer, narrowed to a region or a store.

region defaults to the client's binding; pass 0 for the national ones and leave both arguments out on an unbound client to enumerate every leaflet.

return one leaflet with its pages, by slug or by uuid.

food leaflets carry page images and no product data at all; only bazar leaflets fill :attr:LidlLeaflet.products. slugs embed the week and a random suffix and change every week, so resolve one through :meth:get_leaflets rather than caching it.

search one page of products.

the cursor is the storefront's own nextPageToken, passed back verbatim. it is session scoped, so it only works from the client that produced it — the cookies that scope it live on this client and are replayed for you. category_id narrows the search to one category, sort reorders it, and filters takes a mapping of filter group id to one or more attribute ids.

queries longer than fifty characters are truncated, as the storefront truncates its own.

return one product sheet by its numeric retailerProductId.

the internal product uuid that listings, similar and related speak is not accepted here; it is kept on :attr:~supermercapy.bonpreu.BonpreuProduct.product_uuid.

return the whole category tree, nested, in one request.

this is the one path that kept answering while the challenge was active, so treat it as the cheap call and the health check. depth trims the tree to fewer levels; the default is the full four.

return one category with its children and its first page of products.

an unknown category answers http 404, which raises :class:~supermercapy.NotFoundError. until september 2026 it answered with the root pseudo-category and a generic page instead, so the category the listing reports serving is still checked against the one that was asked for, and a mismatch raises the same error.

return every product the storefront collects under "novetats".

membership of that category is what marks a product new here; the isNew flag on a row is about the row, not the category. the category is read in pages of three hundred, the largest the listing serves, until the count it reports on the first page is reached: two requests for the 510 products it held in october 2026.

return the first page of the shop-wide promotions listing.

:meth:get_promotions is the same listing with paging, a category filter, and the page's own filter and sort metadata.

return one page of the promotions listing, whole shop or one category.

unlike the category listing this one takes either identifier: a category_id uuid or the hierarchical retailer_category_id code such as "0301".

return the autocomplete suggestions for a partial search term.

return the products the storefront offers as similar to one product.

the endpoint answers with internal uuids alone, so the rows are resolved with one batch request; an empty answer costs nothing more.

return the products the storefront cross-sells with one product.

check that dia delivers to a postcode and return a client bound to it.

two requests: the storefront's own delivery check, which also names the store that would serve the postcode, and the move of the client's anonymous session to it. a postcode dia does not deliver to raises :class:~supermercapy.OutOfCoverageError after the first.

search one page of products.

the cursor is the next row offset as a string. the storefront pages by number with at least thirty rows a page and refuses a page above fifty, so the client picks the page that holds the rows asked for and trims it, which keeps any page_size from one to a thousand exact.

return one product sheet by its sku.

dia answers an unknown sku with http 500 rather than 404, so a 500 from the sheet is checked with one search for the sku: no hit raises :class:~supermercapy.NotFoundError, a hit means the sheet really failed and raises :class:~supermercapy.TransportError.

return the two-level category tree in one request.

return one category with its children and its first listing page.

this costs one request for the tree and one for the listing. a top-level category lists its children one after another, so its first page holds the first child's products; product_count is the whole category's. "novedades y recomendados" has no listing of its own (the storefront redirects it to its first child), so it comes back without products.

yield every product by walking each top-level category in turn.

one request for the tree, then one per twenty rows of each child category: an estimated 450 requests for the 6,500 rows the tree held in october 2026. a product listed in two categories is yielded twice; :meth:get_catalog keeps one.

return the products of the storefront's own "novedades" category.

every row of it carries the "novedad" stamp. it costs one request for the tree and one per twenty products: three for the 38 it held in october 2026. rows stamped "novedad" also turn up elsewhere with is_new set, and not all of them are in this category.

return every product on offer, across every category.

the offers page groups its rows by category and shows ten of each, so the client reads the first group's id from it and then walks each category's own offer listing, which chains to the next category: one request, then one per category with offers and one more per extra page of twenty-four, about thirty in october 2026. a product offered in two categories is returned once.

return one page of a category's listing, twenty rows at a time.

without a cursor this costs one request for the tree and one for the page; with the next_cursor of an earlier page it costs one. a top-level category walks its children one after another, and each page's category_id names the child it came from.

return every product on offer in one category, top-level or not.

one request per twenty-four offers.

return a client for the price region of a postcode's province.

this makes no request: balearic postcodes (07) map to the balearic region, las palmas (35) and santa cruz de tenerife (38) to the canary one, and every other province, ceuta and melilla included, to the península.

search one page of the region's index.

the cursor is the next row offset as a string; algolia serves any window of up to a thousand rows.

return one product record by its numeric object id, in one request.

return the top-level categories of the site's product overview.

one request reads the overview page. deep=True adds each category's children at one more request per category, twenty more in october 2026. categories the site hides, such as an out-of-season "verano", are left out.

return one category with its children and every product it lists.

two requests: the category page, for the node, its children and the filter the site lists it with, and one query of the region's index for up to a thousand products. a top-level page lists no products of its own, so its products are those of all its children together.

yield every record of the region's index, a thousand per request.

three requests for the 2,342 records of the península index in october 2026.

return this week's offers, once each, in the order the page lists them.

one request for the region's offers page, which embeds every record it shows. :meth:get_offer_groups keeps the page's sections and their dates.

return the sections of this week's offers page with their dates.

return one page of the products filed under a category key.

the key is what a product's category_ids and :attr:AldiCategory.key hold, so this reaches a product's category in one request without its page.

search one page of products; the cursor is the next offset.

the grid publishes no total, so total_hits is None, and a page shorter than page_size is the last one.

return one product's record, the json its page reads, in one request.

an unknown id is answered with http 500 and an error document, the same answer a server fault gets, so both raise :class:~supermercapy.NotFoundError.

return the category tree from the home page's menu, about 790 kb.

the tree is kept on the client, so a later :meth:get_category needs no second copy.

return one category with its children and its first listing page.

the name and the children come from the menu, which a client that has not read it yet reads first: two requests, then one per category. an id the menu does not hold raises :class:~supermercapy.NotFoundError. no product count is published.

yield every product by walking the catalogue's root a hundred at a time.

the root category holds the whole catalogue: a full walk on 4 october 2026 read 7,579 products in 76 requests of about a megabyte each, and took nine minutes because each page took about seven seconds.

return every product in the menu's offers branch, walked to the end.

return one listing page of a category, its subtree included.

the id is the menu's, such as "cordero_y_cabrito", and the call needs no menu. the storefront answers an unknown id with the whole catalogue rather than an error, so the category the grid reports serving is checked and a mismatch raises :class:~supermercapy.NotFoundError.

search one page of products.

the cursor is the storefront's own nextPageToken, passed back verbatim. it is session scoped, so it only works from the client that produced it. category_id narrows the search to one category, sort reorders it, and filters takes a mapping of filter group id to one or more attribute ids.

queries longer than fifty characters are truncated, as the storefront truncates its own.

return one product sheet by its numeric retailerProductId.

the internal product uuid that listings, similar and related speak is not accepted here; it is kept on :attr:~supermercapy.alcampo.AlcampoProduct.product_uuid.

return the whole category tree, nested, in one request.

depth trims the tree to fewer levels; the default is the full four.

return one category with its children and its first page of products.

an unknown category raises :class:~supermercapy.NotFoundError, and so does a listing that echoes back a category other than the one asked for. the category's product_count is the storefront's own count and can exceed what the bound region lists.

return the click-and-collect points, with the region behind each.

one request returns every point in the country. with a postal_code the list keeps the points in its province, those in the postal code itself first.

return every product the storefront's "nuevo producto" filter selects.

the filter is the storefront's own, offered on every listing in its dummyValue group; applied to the whole-shop listing it is the novelties list. it is read in pages of three hundred until no page follows: one request for the 75 products it held in october 2026.

return the first page of the region's promotions listing.

:meth:get_promotions is the same listing with paging, a category filter, and the page's own filter and sort metadata.

return one page of the promotions listing, whole shop or one category.

the listing is keyed on the client's region. unlike the category listing it takes either identifier: a category_id uuid or the retailer_category_id code such as "OC1701".

return the autocomplete suggestions for a partial search term.

return the products the storefront offers as similar to one product.

the endpoint answers with internal uuids alone, so the rows are resolved with one batch request; an empty answer costs nothing more.

return the products the storefront cross-sells with one product.

bind the picking centre the storefront assigns to postal_code.

the storefront resolves a postcode with a next.js server action, fetchPostalCodeById, whose id changes with every deployment and is published only inside the page's scripts. so this reads the home page, then its scripts in the order the page lists them until one names the action, then calls it. in october 2026 that was eighteen requests: the home page through the anonymous sign-in (five), twelve scripts of about 1.4 mb together, and the call. a postcode condis does not deliver to raises :class:~supermercapy.OutOfCoverageError.

search one page of the index.

the cursor is the offset of the next row. filters takes the index's own "facet:value" strings, as its facets name them, such as "on_sale:true" or "filterCategory:c07", each sent as one filter parameter. one query reaches at most 2,494 rows plus one page; a page against that ceiling with rows left is flagged truncated.

return one product sheet, read from its server-rendered page.

the slug in a product url is not checked, so this asks for a placeholder one and reads the real address from the page. an id the shop does not know renders the page without a product, which raises :class:~supermercapy.NotFoundError.

return the category tree, three levels deep.

the tree is the storefront's own navigation, read from the home page: one request of about 250 kb, plus the anonymous sign-in on a client's first storefront request.

return one category with its children and its first page of rows.

product_count is the number of rows the index holds for the category at the bound picking centre; :meth:get_category_products pages through them. two requests: the tree, then the rows.

yield every row of every top-level category at the picking centre.

each top-level category is walked five hundred rows at a time; the largest held 1,541 rows in october 2026, under the index's offset ceiling. a category too large to walk to its end is walked through its children instead.

return every row the index flags is_novelty.

one request for the 57 it held in october 2026.

return every row on sale or on promotion, once each.

on_sale marks a reduced price and on_promotion a multibuy such as "llévate 6 y paga 5"; the two facets are read one after the other, five hundred rows a request, about three requests in october 2026.

return one page of a category's rows, any level of the tree.

the id is the path-shaped one the tree uses, such as "c07__cat00210003"; an unknown id answers an empty page.

return the index's query suggestions for a partial term.

close the wrapped client once the calls already queued have run.

run call with the client in a worker thread and return its result.

this reaches everything the awaitable methods do not: store extensions, and the extra keywords a store adds to a standard method, with the store's own return types, as in await lidl.run(lambda client: client.get_leaflets()).

yield what an iterator-returning method of the client yields.

the method and each step of its iterator run in a worker thread, so a page is fetched only when the loop asks for its first item, and leaving the loop early costs no request. other calls on this client may run between two steps.

await :meth:BaseClient.search_products.

await :meth:BaseClient.get_product.

await :meth:BaseClient.get_categories.

await :meth:BaseClient.get_category.

iterate :meth:BaseClient.iter_search without blocking the loop.

iterate :meth:BaseClient.iter_catalog without blocking the loop.

await :meth:BaseClient.get_catalog, the whole walk in one call.

await :meth:BaseClient.list_stores.

await :meth:BaseClient.get_product_by_ean.

await :meth:BaseClient.get_new_arrivals.

await :meth:BaseClient.get_offers.

await :meth:BaseClient.get_home.

await :meth:BaseClient.download.

answer request from memory, or send it and keep what may be kept.

forget every stored response.

forget every stored response and close the wrapped transport.