{ "openapi": "3.0.3", "info": { "title": "Mercadona API", "version": "1.0.0" }, "paths": { "/mercadona/search": { "get": { "tags": [ "Products" ], "summary": "Get Search", "description": "Free-text product search. Returns the 100 best matches at most (Mercadona's search limit) as list rows with `ean`; `total` is the true count. Narrow broad queries with `category_id` / `brand`, or use `/category-products` and `/brand-products` for exhaustive lists.", "operationId": "get_search_mercadona_search_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Free-text search, typo-tolerant (e.g. `leche`). Returns at most the 100 best matches per query (Mercadona's search limit); `total` still reports the true match count. For broad terms narrow with `category_id` or `brand` (each gets its own 100), or use `/category-products` and `/brand-products` for exhaustive listings. Empty, `*`, an EAN or a product id return 0 results.", "title": "Q" }, "description": "Free-text search, typo-tolerant (e.g. `leche`). Returns at most the 100 best matches per query (Mercadona's search limit); `total` still reports the true match count. For broad terms narrow with `category_id` or `brand` (each gets its own 100), or use `/category-products` and `/brand-products` for exhaustive listings. Empty, `*`, an EAN or a product id return 0 results." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub (`vlc1 mad1 mad2 mad3 bcn1 svq1 alc1`) or numeric store code from /mercadona/warehouses. Unknown codes are rejected with 400. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `popularity_score` is null on their rows.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub (`vlc1 mad1 mad2 mad3 bcn1 svq1 alc1`) or numeric store code from /mercadona/warehouses. Unknown codes are rejected with 400. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `popularity_score` is null on their rows." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code; resolved to the warehouse the shop would use (per district), takes precedence over `warehouse`. Out of area → empty results with `resolved_filters.warehouse.source = \"not_found\"`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code; resolved to the warehouse the shop would use (per district), takes precedence over `warehouse`. Out of area → empty results with `resolved_filters.warehouse.source = \"not_found\"`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page. Mercadona's search returns at most 100 results, so pages past `total_pages` are empty.", "default": 1, "title": "Page" }, "description": "1-indexed page. Mercadona's search returns at most 100 results, so pages past `total_pages` are empty." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Results per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Results per page, max 20." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Category id at any level (see /mercadona/categories).", "title": "Category Id", "nullable": true }, "description": "Category id at any level (see /mercadona/categories)." }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed. Combined with category_id, the category filter is applied locally over the matched hits.", "title": "Brand", "nullable": true }, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed. Combined with category_id, the category filter is applied locally over the matched hits." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache and fetch fresh data now.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache and fetch fresh data now." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca` — translates names, categories and descriptions; EAN and prices are language-independent. The query is matched against product names in this language: `q=leche` finds 313 products in `es` but only 8 in `en` (use `q=milk`).", "default": "es" }, "description": "`es` (default), `en` or `ca` — translates names, categories and descriptions; EAN and prices are language-independent. The query is matched against product names in this language: `q=leche` finds 313 products in `es` but only 8 in `en` (use `q=milk`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/product-details": { "get": { "tags": [ "Products" ], "summary": "Get Product Details", "description": "Full product entity by `product_id` or `ean` (barcode). Not stocked / unknown → `status: false` envelope.", "operationId": "get_product_details_mercadona_product_details_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "product_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Mercadona product id, passed verbatim (decimal ids like `81241.3` exist; `81241` is a different, unknown id). Exactly one of product_id / ean is required.", "title": "Product Id", "nullable": true }, "description": "Mercadona product id, passed verbatim (decimal ids like `81241.3` exist; `81241` is a different, unknown id). Exactly one of product_id / ean is required." }, { "name": "ean", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{8,14}$", "description": "Barcode (EAN-13; counter items carry internal `2105…` codes). Looked up by barcode; the response is the same as for `product_id`.", "title": "Ean", "nullable": true }, "description": "Barcode (EAN-13; counter items carry internal `2105…` codes). Looked up by barcode; the response is the same as for `product_id`." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code; the product must be stocked there. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `popularity_score` is null on their rows.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code; the product must be stocked there. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `popularity_score` is null on their rows." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the product cache (1 h; 20 min when availability is restricted) and fetch fresh data now.", "default": false, "title": "Fresh" }, "description": "Bypass the product cache (1 h; 20 min when availability is restricted) and fetch fresh data now." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`. Only the name and category names are translated; description, ingredients, allergens and the other texts stay in Spanish.", "default": "es" }, "description": "`es` (default), `en` or `ca`. Only the name and category names are translated; description, ingredients, allergens and the other texts stay in Spanish." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/product-related-products": { "get": { "tags": [ "Products" ], "summary": "Get Product Related Products", "description": "Products Mercadona suggests alongside this one (cross-selling, e.g. olive oils for a salt), up to 10 in Mercadona's order — not variants of the same product. `exclude` is the only paging: pass seen ids to back-fill.", "operationId": "get_product_related_products_mercadona_product_related_products_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Mercadona product id. Unknown ids answer an empty list, not a not-found envelope.", "title": "Product Id" }, "description": "Mercadona product id. Unknown ids answer an empty list, not a not-found envelope." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "exclude", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?(?:,[0-9]+(?:\\.[0-9]+)?)*$", "description": "Comma-separated product ids to leave out; the list is back-filled to 10 — pass the ids you have already seen to page through the ranked list.", "title": "Exclude", "nullable": true }, "description": "Comma-separated product ids to leave out; the list is back-filled to 10 — pass the ids you have already seen to page through the ranked list." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRelatedProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/categories": { "get": { "tags": [ "Catalog" ], "summary": "Get Categories", "description": "Category tree (identical across warehouses): 26 level-0 → 152 level-1; `depth=3` adds the level-2 groups.", "operationId": "get_categories_mercadona_categories_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "depth", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/CategoriesDepth" } ], "description": "`2` (default): 26 level-0 → 152 level-1 categories. `3`: also the level-2 groups inside each category; when they are not available yet the answer is depth 2 and `depth_available` says so.", "default": 2 }, "description": "`2` (default): 26 level-0 → 152 level-1 categories. `3`: also the level-2 groups inside each category; when they are not available yet the answer is depth 2 and `depth_available` says so." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 15-minute cache.", "default": false, "title": "Fresh" }, "description": "Bypass the 15-minute cache." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/category-products": { "get": { "tags": [ "Catalog" ], "summary": "Get Category", "description": "Products of a level-1 category (flattened over its groups, de-duplicated, paginated locally). A level-2 id lists that group; a level-0 id answers `status: false` with `error.children` = its level-1 categories to call instead.", "operationId": "get_category_mercadona_category_products_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "category_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Level-1 category id (e.g. `112`). A level-2 id is resolved to its parent and filtered to that group, in any warehouse; a level-0 id answers `status: false` with `error.code = level_0_category` and `error.children[]` listing its level-1 ids.", "title": "Category Id" }, "description": "Level-1 category id (e.g. `112`). A level-2 id is resolved to its parent and filtered to that group, in any warehouse; a level-0 id answers `status: false` with `error.code = level_0_category` and `error.children[]` listing its level-1 ids." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code (assortment and ≈100 prices differ per warehouse). Default `vlc1`; ignored when `postal_code` is given.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code (assortment and ≈100 prices differ per warehouse). Default `vlc1`; ignored when `postal_code` is given." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page over the flattened, de-duplicated product list.", "default": 1, "title": "Page" }, "description": "1-indexed page over the flattened, de-duplicated product list." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Items per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Items per page, max 20." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/brands": { "get": { "tags": [ "Catalog" ], "summary": "Get Brands", "description": "Brand vocabulary for `brand=` (exact names, no ids) with product counts; global or per warehouse.", "operationId": "get_brands_mercadona_brands_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Case- and accent-insensitive substring match on the brand name (`dan` → Danone, Danacol; `hac` → Hacendado, La Hacienda del Ibérico). Omit for the full list.", "title": "Q", "nullable": true }, "description": "Case- and accent-insensitive substring match on the brand name (`dan` → Danone, Danacol; `hac` → Hacendado, La Hacienda del Ibérico). Omit for the full list." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Restrict to one warehouse's assortment and counts. Omit for the union over the 7 hubs.", "title": "Warehouse", "nullable": true }, "description": "Restrict to one warehouse's assortment and counts. Omit for the union over the 7 hubs." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Only brands with products in this category (any level).", "title": "Category Id", "nullable": true }, "description": "Only brands with products in this category (any level)." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day.", "default": false, "title": "Fresh" }, "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echoed only — brand names are not translated, the list is the same in every language.", "default": "es" }, "description": "Echoed only — brand names are not translated, the list is the same in every language." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/brand-products": { "get": { "tags": [ "Catalog" ], "summary": "Get Brand Products", "description": "Products of one brand (exact name from /mercadona/brands), paginated.", "operationId": "get_brand_products_mercadona_brand_products_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 150, "description": "Exact brand name as Mercadona writes it (from /mercadona/brands; `Como Tú` and `Como tú` are different brands). Unknown → empty results with `resolved_filters.brand.source = \"not_found\"`. Returns every product of the brand; for a keyword inside a brand use /mercadona/search with `brand`.", "title": "Brand" }, "description": "Exact brand name as Mercadona writes it (from /mercadona/brands; `Como Tú` and `Como tú` are different brands). Unknown → empty results with `resolved_filters.brand.source = \"not_found\"`. Returns every product of the brand; for a keyword inside a brand use /mercadona/search with `brand`." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page.", "default": 1, "title": "Page" }, "description": "1-indexed page." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Results per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Results per page, max 20." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Category id at any level.", "title": "Category Id", "nullable": true }, "description": "Category id at any level." }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set.", "title": "Min Price", "nullable": true }, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`.", "title": "Max Price", "nullable": true }, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`." }, { "name": "sort", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/BrandProductsSort" } ], "description": "`popularity` (default, most popular first), `price_asc`, `price_desc`.", "default": "popularity" }, "description": "`popularity` (default, most popular first), `price_asc`, `price_desc`." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day.", "default": false, "title": "Fresh" }, "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/price-drops": { "get": { "tags": [ "Discovery" ], "summary": "Get Offers", "description": "Products currently on a price drop (`is_price_drop: true`), with discount value and percentage.", "operationId": "get_offers_mercadona_price_drops_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows, and `brand` or a level-1/2 `category_id` answer 400 for them.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows, and `brand` or a level-1/2 `category_id` answer 400 for them." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page.", "default": 1, "title": "Page" }, "description": "1-indexed page." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Items per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Items per page, max 20." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Category id at any level.", "title": "Category Id", "nullable": true }, "description": "Category id at any level." }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`).", "title": "Brand", "nullable": true }, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`)." }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set.", "title": "Min Price", "nullable": true }, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`.", "title": "Max Price", "nullable": true }, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`." }, { "name": "sort", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/OffersSort" } ], "description": "`discount_percent` (default, biggest cut in % first), `discount_value` (biggest saving in euros first), `popularity` (most popular first), `price_asc`, `price_desc`; ties by `product_id`, except that when the answer has `source: live`, `popularity` keeps Mercadona's own price-drop order (no popularity data for that warehouse).", "default": "discount_percent" }, "description": "`discount_percent` (default, biggest cut in % first), `discount_value` (biggest saving in euros first), `popularity` (most popular first), `price_asc`, `price_desc`; ties by `product_id`, except that when the answer has `source: live`, `popularity` keeps Mercadona's own price-drop order (no popularity data for that warehouse)." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day.", "default": false, "title": "Fresh" }, "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/new-products": { "get": { "tags": [ "Discovery" ], "summary": "Get New Products", "description": "New arrivals: the Novedades grid, or `feed=all` for the union with every \"Nuevo en …\" section.", "operationId": "get_new_products_mercadona_new_products_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows, and `brand` or a level-1/2 `category_id` answer 400 for them.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows, and `brand` or a level-1/2 `category_id` answer 400 for them." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page (local pagination).", "default": 1, "title": "Page" }, "description": "1-indexed page (local pagination)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Items per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Items per page, max 20." }, { "name": "feed", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/NewProductsFeed" } ], "description": "`novedades` (default): the general Novedades grid. `all`: also every home section titled \"Nuevo en …\".", "default": "novedades" }, "description": "`novedades` (default): the general Novedades grid. `all`: also every home section titled \"Nuevo en …\"." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Category id at any level.", "title": "Category Id", "nullable": true }, "description": "Category id at any level." }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`).", "title": "Brand", "nullable": true }, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`)." }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set.", "title": "Min Price", "nullable": true }, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`.", "title": "Max Price", "nullable": true }, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache of the new-products feed. `brand`, `ean`, `category_path` and `popularity_score` come from the daily catalog snapshot (`snapshot_date`) and refresh once a day.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache of the new-products feed. `brand`, `ean`, `category_path` and `popularity_score` come from the daily catalog snapshot (`snapshot_date`) and refresh once a day." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/best-sellers": { "get": { "tags": [ "Discovery" ], "summary": "Get Bestsellers", "description": "Products ordered by Mercadona's internal popularity ranking (`popularity_score` desc) with a continuous `rank`.", "operationId": "get_bestsellers_mercadona_best_sellers_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given. Numeric store codes are served live: `brand`, `ean`, `category_path` and `popularity_score` may be null on their rows." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page.", "default": 1, "title": "Page" }, "description": "1-indexed page." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Results per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Results per page, max 20." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Category id at any level.", "title": "Category Id", "nullable": true }, "description": "Category id at any level." }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`). With one brand the list is the same as /mercadona/brand-products (popularity order) plus `rank`.", "title": "Brand", "nullable": true }, "description": "Exact brand name as Mercadona writes it (see /mercadona/brands). Several brands comma-separated are OR-ed (`Danone,Puleva`). With one brand the list is the same as /mercadona/brand-products (popularity order) plus `rank`." }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set.", "title": "Min Price", "nullable": true }, "description": "Lowest `price_value` in euros, inclusive, 0–10000 (e.g. `2` or `1.5`). `total` counts only the products in the range; products without a price are left out when a bound is set." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 0, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`.", "title": "Max Price", "nullable": true }, "description": "Highest `price_value` in euros, inclusive, 0–10000; must be greater than or equal to `min_price`." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day.", "default": false, "title": "Fresh" }, "description": "Bypass the 15-minute cache. Only affects answers with `source: live`; `catalog_index` answers come from the daily catalog snapshot (`snapshot_date`) and refresh once a day." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestsellersResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/campaigns": { "get": { "tags": [ "Discovery" ], "summary": "Get Campaigns", "description": "Home sections (banners, carousels, the Novedades grid) in display order.", "operationId": "get_campaigns_mercadona_campaigns_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/campaign-products": { "get": { "tags": [ "Discovery" ], "summary": "Get Campaign", "description": "Products of one home section (uuid or slug from /mercadona/campaigns), paginated locally.", "operationId": "get_campaign_mercadona_campaign_products_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "campaign_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{2,63}$", "description": "Section id (uuid or slug) from /mercadona/campaigns. Unknown → `status: false` not-found envelope.", "title": "Campaign Id" }, "description": "Section id (uuid or slug) from /mercadona/campaigns. Unknown → `status: false` not-found envelope." }, { "name": "warehouse", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:[a-z]{3}[0-9]|[0-9]{4})$", "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given.", "default": "vlc1", "title": "Warehouse", "nullable": true }, "description": "Hub or numeric store code. Default `vlc1`; ignored when `postal_code` is given." }, { "name": "postal_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`.", "title": "Postal Code", "nullable": true }, "description": "Spanish 5-digit postal code, resolved to its warehouse; takes precedence over `warehouse`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-indexed page over the section's items (local pagination).", "default": 1, "title": "Page" }, "description": "1-indexed page over the section's items (local pagination)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Items per page, max 20.", "default": 20, "title": "Per Page" }, "description": "Items per page, max 20." }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the 10-minute cache.", "default": false, "title": "Fresh" }, "description": "Bypass the 10-minute cache." }, { "name": "language", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "`es` (default), `en` or `ca`.", "default": "es" }, "description": "`es` (default), `en` or `ca`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/warehouses": { "get": { "tags": [ "Warehouses" ], "summary": "Get Warehouses", "description": "Live Mercadona warehouses: 7 hubs + 267 numeric store codes (static list, refreshed monthly).", "operationId": "get_warehouses_mercadona_warehouses_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/WarehouseType" } ], "description": "`all` (default), `hub` (7 string codes) or `store` (267 numeric store codes).", "default": "all" }, "description": "`all` (default), `hub` (7 string codes) or `store` (267 numeric store codes)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehousesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/resolve-warehouse": { "get": { "tags": [ "Warehouses" ], "summary": "Get Resolve Warehouse", "description": "Postal code → the warehouse the shop would use (per district). Out of area is a real answer, not an error.", "operationId": "get_resolve_warehouse_mercadona_resolve_warehouse_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "postal_code", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Spanish 5-digit postal code, e.g. `08001`.", "title": "Postal Code" }, "description": "Spanish 5-digit postal code, e.g. `08001`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveWarehouseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mercadona/health": { "get": { "summary": " Health Check", "description": "Health check endpoint - publicly accessible without authentication", "operationId": "_health_check_mercadona_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/mercadona/ping": { "get": { "summary": " Health Check", "description": "Health check endpoint - publicly accessible without authentication", "operationId": "_health_check_mercadona_ping_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "Language": { "type": "string", "enum": [ "es", "en", "ca" ], "title": "Language" }, "ProductRelatedProductsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/ProductRelatedProductsData" } ], "description": "Related products; empty list for an unknown id.", "nullable": true } }, "type": "object", "title": "ProductRelatedProductsResponse" }, "CategoryResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/CategoryData" } ], "description": "Category listing; null with `error.code = not_found` for an unknown id.", "nullable": true } }, "type": "object", "title": "CategoryResponse" }, "CampaignsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/CampaignsData" } ], "description": "Campaign list.", "nullable": true } }, "type": "object", "title": "CampaignsResponse" }, "NewProductsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/NewProductsData" } ], "description": "New products.", "nullable": true } }, "type": "object", "title": "NewProductsResponse" }, "NewProductsFeed": { "type": "string", "enum": [ "novedades", "all" ], "title": "NewProductsFeed" }, "CampaignsData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CampaignSummary" }, "type": "array", "title": "Items", "description": "Home sections in display order (the login notification is skipped)." }, "total": { "type": "integer", "title": "Total", "description": "Number of items." }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "resolved_filters", "language" ], "title": "CampaignsData" }, "ResolveWarehouseResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/ResolveWarehouseData" } ], "description": "Resolution result.", "nullable": true } }, "type": "object", "title": "ResolveWarehouseResponse" }, "CategoryData": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Level-1 category id." }, "name": { "type": "string", "title": "Name", "description": "Category name." }, "order": { "type": "integer", "title": "Order", "description": "Menu order.", "nullable": true }, "groups": { "items": { "$ref": "#/components/schemas/CategoryGroup" }, "type": "array", "title": "Groups", "description": "Level-2 groups with their sizes." }, "items": { "items": { "$ref": "#/components/schemas/CategoryCardRow" }, "type": "array", "title": "Items", "description": "Products of this page — flattened over the groups, de-duplicated (≈ 265 cross-group repeats per warehouse), with `is_new`." }, "total": { "type": "integer", "title": "Total", "description": "Unique products in the category." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "next_category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Next level-1 category in menu order.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "category_id", "name", "total", "page", "per_page", "total_pages", "has_next_page", "resolved_filters", "language" ], "title": "CategoryData" }, "WarehousesResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/WarehousesData" } ], "description": "Warehouse list.", "nullable": true } }, "type": "object", "title": "WarehousesResponse" }, "OffersResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/OffersData" } ], "description": "Offers.", "nullable": true } }, "type": "object", "title": "OffersResponse" }, "BrandProductsSort": { "type": "string", "enum": [ "popularity", "price_asc", "price_desc" ], "title": "BrandProductsSort" }, "BrandsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/BrandsData" } ], "description": "Brand list.", "nullable": true } }, "type": "object", "title": "BrandsResponse" }, "CategoriesResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/CategoriesData" } ], "description": "Category tree.", "nullable": true } }, "type": "object", "title": "CategoriesResponse" }, "ProductRelatedProductsData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CardRow" }, "type": "array", "title": "Items", "description": "Up to 10 products Mercadona suggests alongside the requested one (cross-selling), in Mercadona's order." }, "total": { "type": "integer", "title": "Total", "description": "Number of items returned (≤ 10)." }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "resolved_filters", "language" ], "title": "ProductRelatedProductsData" }, "SearchResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/SearchData" } ], "description": "Search payload.", "nullable": true } }, "type": "object", "title": "SearchResponse" }, "ResolveWarehouseData": { "properties": { "postal_code": { "type": "string", "title": "Postal Code", "description": "Echo of the postal code." }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse the shop uses for this postal code; null when out of area.", "nullable": true }, "warehouse_type": { "allOf": [ { "$ref": "#/components/schemas/WarehouseType" } ], "description": "`hub` or `store`; null when out of area.", "nullable": true }, "in_area": { "type": "boolean", "title": "In Area", "description": "False when Mercadona answers \"outside of our working area\" (a real answer, not an error)." } }, "type": "object", "required": [ "postal_code", "in_area" ], "title": "ResolveWarehouseData" }, "OffersSort": { "type": "string", "enum": [ "discount_percent", "discount_value", "popularity", "price_asc", "price_desc" ], "title": "OffersSort" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "WarehousesData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WarehouseItem" }, "type": "array", "title": "Items", "description": "Live warehouses (7 hubs + 267 stores; `vlc2` and `test` are excluded)." }, "total": { "type": "integer", "title": "Total", "description": "Number of items." } }, "type": "object", "required": [ "total" ], "title": "WarehousesData" }, "CategoriesData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CategoryNode" }, "type": "array", "title": "Items", "description": "Level-0 categories with nested children." }, "total": { "type": "integer", "title": "Total", "description": "Number of level-0 categories (26)." }, "depth": { "type": "integer", "title": "Depth", "description": "Echo of `depth`." }, "depth_available": { "type": "integer", "title": "Depth Available", "description": "Depth actually served: equals `depth`, except 2 when `depth=3` was asked but the level-2 groups are not available yet." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "depth", "depth_available", "language" ], "title": "CategoriesData" }, "WarehouseItem": { "properties": { "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse code: hub (`vlc1`) or numeric store code (`4115`)." }, "warehouse_type": { "allOf": [ { "$ref": "#/components/schemas/WarehouseType" } ], "description": "`hub` or `store`." }, "products_count": { "type": "integer", "title": "Products Count", "description": "Products in the warehouse's catalog at the last probe (05 R3).", "nullable": true }, "example_postal_codes": { "items": { "type": "string" }, "type": "array", "title": "Example Postal Codes", "description": "Example postal codes served by this warehouse; may be empty." } }, "type": "object", "required": [ "warehouse", "warehouse_type" ], "title": "WarehouseItem" }, "CategoryGroup": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Level-2 group id." }, "name": { "type": "string", "title": "Name", "description": "Group name." }, "order": { "type": "integer", "title": "Order", "description": "Order inside the level-1 category.", "nullable": true }, "items_count": { "type": "integer", "title": "Items Count", "description": "Products listed in this group (before de-duplication)." } }, "type": "object", "required": [ "category_id", "name", "items_count" ], "title": "CategoryGroup" }, "ProductDetailsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/ProductDetailsData" } ], "description": "Full product entity; null with `error.code = not_found_in_warehouse | ean_not_found`.", "nullable": true } }, "type": "object", "title": "ProductDetailsResponse" }, "ResolvedFilters": { "properties": { "warehouse": { "allOf": [ { "$ref": "#/components/schemas/ResolvedWarehouse" } ], "description": "Warehouse echo. Null only on /mercadona/brands without a warehouse (global answer).", "nullable": true }, "ean": { "allOf": [ { "$ref": "#/components/schemas/ResolvedEan" } ], "description": "Present on /mercadona/product-details when `ean` was given.", "nullable": true }, "brand": { "allOf": [ { "$ref": "#/components/schemas/ResolvedBrand" } ], "description": "Present on /mercadona/brand-products.", "nullable": true }, "brands": { "allOf": [ { "$ref": "#/components/schemas/ResolvedBrands" } ], "description": "Present on /mercadona/search, /price-drops, /new-products and /best-sellers when `brand` was given.", "nullable": true } }, "type": "object", "title": "ResolvedFilters" }, "BestsellersResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/BestsellersData" } ], "description": "Bestsellers.", "nullable": true } }, "type": "object", "title": "BestsellersResponse" }, "CategoryNode": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Category id." }, "name": { "type": "string", "title": "Name", "description": "Category name in the requested language." }, "order": { "type": "integer", "title": "Order", "description": "Menu order.", "nullable": true }, "level": { "type": "integer", "maximum": 2.0, "minimum": 0.0, "title": "Level", "description": "0 / 1 / 2." }, "categories": { "items": { "$ref": "#/components/schemas/CategoryNode" }, "type": "array", "title": "Categories", "description": "Child categories." } }, "type": "object", "required": [ "category_id", "name", "level" ], "title": "CategoryNode" }, "CategoriesDepth": { "type": "integer", "enum": [ 2, 3 ], "title": "CategoriesDepth" }, "ProductDetailsData": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode. Always present on /search rows; on other listings it is null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products; house brands are `Hacendado`, `Deliplus`, `Bosque Verde`…).", "nullable": true }, "category_path": { "items": { "items": { "$ref": "#/components/schemas/CategoryPathNode" }, "type": "array" }, "type": "array", "title": "Category Path", "description": "Full category paths (level 0 → 1 → 2). A product can sit in two trees, hence a list of paths." }, "popularity_score": { "type": "number", "title": "Popularity Score", "description": "Mercadona's internal popularity ranking (undocumented, higher = more popular). Null for products added to the catalog in the last day.", "nullable": true }, "is_new": { "type": "boolean", "title": "Is New", "description": "True when Mercadona lists the product as a new arrival. Null when the answer was served from a recent /mercadona/search result; call again with `fresh=true` for a definitive true/false.", "nullable": true }, "origin": { "type": "string", "title": "Origin", "description": "Country/region of origin, e.g. `España` (≈ 50 % filled).", "nullable": true }, "photos": { "items": { "$ref": "#/components/schemas/Photo" }, "type": "array", "title": "Photos", "description": "Photo gallery (avg 2.2 photos)." }, "ingredients": { "type": "string", "title": "Ingredients", "description": "Ingredients as HTML (allergens in ``). Mercadona publishes no per-100 g nutrition table.", "nullable": true }, "ingredients_text": { "type": "string", "title": "Ingredients Text", "description": "`ingredients` as plain text: tags removed, entities decoded, line breaks and paragraphs joined by a single space. Null when `ingredients` is null.", "nullable": true }, "allergens": { "type": "string", "title": "Allergens", "description": "Allergen statement as HTML.", "nullable": true }, "allergens_text": { "type": "string", "title": "Allergens Text", "description": "`allergens` as plain text: tags removed, entities decoded, line breaks and paragraphs joined by a single space. Null when `allergens` is null.", "nullable": true }, "legal_name": { "type": "string", "title": "Legal Name", "description": "Legal sales name.", "nullable": true }, "description": { "type": "string", "title": "Description", "description": "Marketing description in the requested language.", "nullable": true }, "suppliers": { "items": { "type": "string" }, "type": "array", "title": "Suppliers", "description": "Supplier names." }, "storage_instructions": { "type": "string", "title": "Storage Instructions", "description": "Storage instructions.", "nullable": true }, "usage_instructions": { "type": "string", "title": "Usage Instructions", "description": "Usage instructions.", "nullable": true }, "mandatory_mentions": { "type": "string", "title": "Mandatory Mentions", "description": "Legally mandatory mentions.", "nullable": true }, "danger_mentions": { "type": "string", "title": "Danger Mentions", "description": "Hazard statements (0/764 filled in the sample; kept for contract parity).", "nullable": true }, "alcohol_by_volume": { "type": "string", "title": "Alcohol By Volume", "description": "Alcohol content as shown, e.g. `13.5º` (wine/beer only).", "nullable": true }, "alcohol_by_volume_value": { "type": "number", "title": "Alcohol By Volume Value", "description": "`alcohol_by_volume` as a number (percent alcohol by volume), e.g. `13.5`. Null when `alcohol_by_volume` is null or not a plain number.", "nullable": true }, "counter_info": { "type": "string", "title": "Counter Info", "description": "Counter-service note (fish / bakery items only).", "nullable": true }, "production_variant": { "type": "string", "title": "Production Variant", "description": "Free-text production note (≈ 4 %).", "nullable": true }, "is_prepared_by_mercadona": { "type": "boolean", "title": "Is Prepared By Mercadona", "description": "True for products prepared by Mercadona (bakery, ready meals); null when not stated.", "nullable": true }, "is_bulk": { "type": "boolean", "title": "Is Bulk", "description": "Sold loose at a counter.", "default": false }, "is_variable_weight": { "type": "boolean", "title": "Is Variable Weight", "description": "Price depends on the weighed amount.", "default": false }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the catalog snapshot that supplied popularity and catalog fields; price and stock are live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo (+ `ean` echo when looked up by EAN)." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "product_id", "name", "availability", "resolved_filters", "language" ], "title": "ProductDetailsData" }, "CampaignResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/CampaignData" } ], "description": "Section items; null with `error.code = not_found` for an unknown id.", "nullable": true } }, "type": "object", "title": "CampaignResponse" }, "WarehouseType": { "type": "string", "enum": [ "hub", "store", "all" ], "title": "WarehouseType" }, "NotFoundError": { "properties": { "code": { "type": "string", "title": "Code", "description": "One of: `out_of_area` (the postal code is outside Mercadona's delivery area), `not_found_in_warehouse` (product id unknown or not stocked in this warehouse), `ean_not_found` (barcode unknown), `not_found` (category / campaign unknown), `level_0_category` (a top-level category id on /category-products — `children` lists the level-1 ids to use)." }, "message": { "type": "string", "title": "Message", "description": "Plain-English explanation of the not-found answer." }, "children": { "items": { "$ref": "#/components/schemas/CategoryRef" }, "type": "array", "title": "Children", "description": "Only with `level_0_category`: the level-1 categories under the requested id, each usable as `category_id` on /category-products.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse that answered (hub like `vlc1` or numeric store code like `4115`). Null when no warehouse was involved (unknown EAN).", "nullable": true } }, "type": "object", "required": [ "code", "message" ], "title": "NotFoundError", "description": "Machine-readable reason on a `status: false` not-found envelope." }, "Availability": { "properties": { "in_stock": { "type": "boolean", "title": "In Stock", "description": "`published` and no `status` flag. False ≈ 1 % of rows (e.g. `temporarily_unavailable`)." }, "status": { "type": "string", "title": "Status", "description": "Availability status as Mercadona reports it, e.g. `temporarily_unavailable`. Sparse: set only for seasonal or weekday-restricted products; null otherwise.", "nullable": true }, "unavailable_from": { "type": "string", "title": "Unavailable From", "description": "ISO-8601 datetime from which the product is unavailable. Sparse: set only for seasonal products; null otherwise.", "nullable": true }, "unavailable_weekdays": { "items": { "type": "integer" }, "type": "array", "title": "Unavailable Weekdays", "description": "ISO weekday numbers on which the product cannot be ordered (fresh fish, e.g. `[1]`). Sparse: set only for weekday-restricted products; empty otherwise." }, "order_limit": { "type": "integer", "title": "Order Limit", "description": "Maximum units per order; 999 means no practical limit (e.g. 20 on sliced ibérico, 10 on whisky).", "nullable": true } }, "type": "object", "required": [ "in_stock" ], "title": "Availability", "description": "Availability state. A state, never a quantity — Mercadona exposes no stock counts." }, "Photo": { "properties": { "zoom": { "type": "string", "title": "Zoom", "description": "Largest image URL (1600 or 3600 px).", "nullable": true }, "regular": { "type": "string", "title": "Regular", "description": "600 px image URL.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "perspective": { "type": "integer", "title": "Perspective", "description": "Shot angle index (0 = front).", "nullable": true } }, "type": "object", "title": "Photo" }, "CampaignSummary": { "properties": { "campaign_id": { "type": "string", "title": "Campaign Id", "description": "Section id to pass to /mercadona/campaign-products (uuid or slug)." }, "title": { "type": "string", "title": "Title", "description": "Section title in the requested language." }, "subtitle": { "type": "string", "title": "Subtitle", "description": "Section subtitle; null/empty for most.", "nullable": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/CampaignType" } ], "description": "`banner`, `carousel` or `grid` (the Novedades grid)." }, "section_code": { "type": "string", "title": "Section Code", "description": "Mercadona's code for the kind of home section: `PD` price drops, `NA` new arrivals (Novedades), `RE` products that are back (\"Han vuelto\"), `PS` themed carousel, `SN` seasonal campaign; anything else is another kind. Informational only — no endpoint filters on it. Null for banners.", "nullable": true }, "image_url": { "type": "string", "title": "Image Url", "description": "Banner image URL; null for carousels/grids.", "nullable": true }, "items_count": { "type": "integer", "title": "Items Count", "description": "Products shown in the home preview of this section (10 for carousels, ≈ 50 for the grid); null for banners, whose items need /mercadona/campaign-products.", "nullable": true } }, "type": "object", "required": [ "campaign_id", "title", "type" ], "title": "CampaignSummary" }, "BrandProductsResponse": { "properties": { "status": { "type": "boolean", "title": "Status", "description": "True on success and on empty results; false only on a not-found envelope (`error` set, `data` null).", "default": true }, "cached_at": { "type": "string", "title": "Cached At", "description": "ISO-8601 UTC time at which this data was fetched from Mercadona; null when it was fetched for this request.", "nullable": true }, "error": { "allOf": [ { "$ref": "#/components/schemas/NotFoundError" } ], "description": "Present only when `status` is false.", "nullable": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/BrandProductsData" } ], "description": "Brand products; empty with `resolved_filters.brand.source = not_found` for an unknown brand.", "nullable": true } }, "type": "object", "title": "BrandProductsResponse" }, "CategoryRef": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Category id." }, "name": { "type": "string", "title": "Name", "description": "Category name in the requested language." } }, "type": "object", "required": [ "category_id", "name" ], "title": "CategoryRef" }, "BestsellersData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BestsellerRow" }, "type": "array", "title": "Items", "description": "Products ordered by `popularity_score` desc (ties by product_id), with `rank`." }, "total": { "type": "integer", "title": "Total", "description": "Products in scope. With `source: live` (store codes) the list covers at most 1,000 products and `total` reflects that cap." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "source": { "allOf": [ { "$ref": "#/components/schemas/DataSource" } ], "description": "`catalog_index`: served from the daily catalog snapshot. `live`: fetched from Mercadona now (top 1,000 products only)." }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the daily catalog snapshot when `source = catalog_index`; null when live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "page", "per_page", "total_pages", "has_next_page", "source", "resolved_filters", "language" ], "title": "BestsellersData" }, "NewProductsData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ListRow" }, "type": "array", "title": "Items", "description": "New products, list row (every item is a new arrival by construction — no `is_new` field)." }, "total": { "type": "integer", "title": "Total", "description": "Products matching the filters." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "feed": { "allOf": [ { "$ref": "#/components/schemas/NewProductsFeed" } ], "description": "Echo of `feed`." }, "source": { "allOf": [ { "$ref": "#/components/schemas/DataSource" } ], "description": "`catalog_index`: enriched from the daily catalog snapshot. `live`: fetched from Mercadona now (store codes). Same meaning as on every other list endpoint." }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the daily catalog snapshot when `source = catalog_index`; null when live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "page", "per_page", "total_pages", "has_next_page", "feed", "source", "resolved_filters", "language" ], "title": "NewProductsData" }, "OffersData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/OfferRow" }, "type": "array", "title": "Items", "description": "Products with a was-price (`is_price_drop: true`), list row + discount fields." }, "total": { "type": "integer", "title": "Total", "description": "Offers matching the filters (≈ 150–160 per warehouse)." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "sort": { "allOf": [ { "$ref": "#/components/schemas/OffersSort" } ], "description": "Echo of `sort`." }, "source": { "allOf": [ { "$ref": "#/components/schemas/DataSource" } ], "description": "`catalog_index`: served from the daily catalog snapshot. `live`: fetched from Mercadona now (store codes)." }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the daily catalog snapshot when `source = catalog_index`; null when live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "page", "per_page", "total_pages", "has_next_page", "sort", "source", "resolved_filters", "language" ], "title": "OffersData" }, "CardRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true } }, "type": "object", "required": [ "product_id", "name", "availability" ], "title": "CardRow", "description": "Product card: identity, price block and availability. Served by /product-related-products and /campaign-products." }, "CampaignType": { "type": "string", "enum": [ "banner", "carousel", "grid" ], "title": "CampaignType" }, "CategoryCardRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "group": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-2 group of the listing the product appears in (the first one when it is listed in several). Matches one of `groups[]`.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode; null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products and for products added to the catalog in the last day).", "nullable": true }, "is_new": { "type": "boolean", "title": "Is New", "description": "True when Mercadona lists the product as a new arrival (the Novedades grid plus the \"Nuevo en …\" sections).", "nullable": true } }, "type": "object", "required": [ "product_id", "name", "availability" ], "title": "CategoryCardRow", "description": "Product card as served by /category-products: the card plus its group, barcode, brand and the new-arrival flag." }, "ResolvedBrand": { "properties": { "input": { "type": "string", "title": "Input", "description": "The brand string the caller sent." }, "resolved": { "type": "string", "title": "Resolved", "description": "Exact brand string matched (same as input — no fuzzy matching, no spelling-variant merging); null when the brand does not exist in the warehouse.", "nullable": true }, "source": { "allOf": [ { "$ref": "#/components/schemas/BrandResolutionSource" } ], "description": "`param` (exact match) or `not_found` (hint: look it up with /mercadona/brands?q=)." } }, "type": "object", "required": [ "input", "source" ], "title": "ResolvedBrand" }, "ColorVariant": { "properties": { "color": { "type": "string", "title": "Color", "description": "Hex colour of the shade, e.g. `#eacdbd`.", "nullable": true }, "color_description": { "type": "string", "title": "Color Description", "description": "Shade name, e.g. `Multi-Stick 01 iluminador`.", "nullable": true }, "product_id": { "type": "string", "title": "Product Id", "description": "Product id of the sibling shade.", "nullable": true } }, "type": "object", "title": "ColorVariant" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "OfferRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode. Always present on /search rows; on other listings it is null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products; house brands are `Hacendado`, `Deliplus`, `Bosque Verde`…).", "nullable": true }, "category_path": { "items": { "items": { "$ref": "#/components/schemas/CategoryPathNode" }, "type": "array" }, "type": "array", "title": "Category Path", "description": "Full category paths (level 0 → 1 → 2). A product can sit in two trees, hence a list of paths." }, "popularity_score": { "type": "number", "title": "Popularity Score", "description": "Mercadona's internal popularity ranking (undocumented, higher = more popular). Null for products added to the catalog in the last day.", "nullable": true }, "discount_value": { "type": "number", "title": "Discount Value", "description": "`previous_price_value − price_value`, 2 decimals, EUR.", "nullable": true }, "discount_percent": { "type": "number", "title": "Discount Percent", "description": "Discount as a percentage of the previous price, 2 decimals.", "nullable": true } }, "type": "object", "required": [ "product_id", "name", "availability" ], "title": "OfferRow" }, "BrandResolutionSource": { "type": "string", "enum": [ "param", "not_found" ], "title": "BrandResolutionSource" }, "CategoryPathNode": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Category id." }, "name": { "type": "string", "title": "Name", "description": "Category name in the requested language." }, "level": { "type": "integer", "maximum": 2.0, "minimum": 0.0, "title": "Level", "description": "0 (department) → 1 (aisle) → 2 (shelf)." } }, "type": "object", "required": [ "category_id", "name", "level" ], "title": "CategoryPathNode" }, "SearchData": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ListRow" }, "type": "array", "title": "Results", "description": "Matched products (list row, detail-grade data via /product-details)." }, "total": { "type": "integer", "title": "Total", "description": "True number of matches. Pages stop at 100 results per query, so `total` can exceed what you can page through; paginate with `total_pages`." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "Pages reachable: `ceil(min(total, 100) / per_page)` — Mercadona's search returns at most 100 results per query." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "brands": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Brands", "description": "Brand → match count over all matches (not only the 100 returned). The empty-string key counts unbranded products; it cannot be used as a `brand` filter." }, "categories": { "items": { "$ref": "#/components/schemas/SearchCategoryNode" }, "type": "array", "title": "Categories", "description": "Matched categories with counts, level 0 → 1 → 2, biggest first; on every query (empty list when nothing matches). Counts cover ALL matches, not only the 100 returned; a product can sit in several categories, so counts may add up to more than `total`. With `brand` + `category_id`, counts describe the brand search before the category is applied. Level-2 groups may be absent for a short time after a catalog refresh.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "page", "per_page", "total_pages", "has_next_page", "resolved_filters", "language" ], "title": "SearchData" }, "BrandsData": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BrandItem" }, "type": "array", "title": "Results", "description": "Brands sorted by products_count desc, then name. Names are exactly as Mercadona spells them; case or accent variants (`La Hacienda del ibérico` / `La Hacienda del Ibérico`) appear as separate entries." }, "total": { "type": "integer", "title": "Total", "description": "Number of brands returned." }, "source": { "allOf": [ { "$ref": "#/components/schemas/DataSource" } ], "description": "`catalog_index`: served from the daily catalog snapshot. `live`: fetched from Mercadona now (then the list covers the `vlc1` assortment only)." }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the daily catalog snapshot when `source = catalog_index`; null when live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo; `warehouse` null when global." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "source", "resolved_filters", "language" ], "title": "BrandsData" }, "BrandProductsData": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BrandProductRow" }, "type": "array", "title": "Results", "description": "Products of the brand, list row + `category_rank`." }, "total": { "type": "integer", "title": "Total", "description": "True number of products of the brand in scope." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "sort": { "allOf": [ { "$ref": "#/components/schemas/BrandProductsSort" } ], "description": "Echo of `sort`." }, "source": { "allOf": [ { "$ref": "#/components/schemas/DataSource" } ], "description": "`catalog_index`: served from the daily catalog snapshot. `live`: fetched from Mercadona now." }, "snapshot_date": { "type": "string", "title": "Snapshot Date", "description": "Date (YYYY-MM-DD) of the daily catalog snapshot when `source = catalog_index`; null when live.", "nullable": true }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse + brand echoes." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "total", "page", "per_page", "total_pages", "has_next_page", "sort", "source", "resolved_filters", "language" ], "title": "BrandProductsData" }, "ListRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode. Always present on /search rows; on other listings it is null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products; house brands are `Hacendado`, `Deliplus`, `Bosque Verde`…).", "nullable": true }, "category_path": { "items": { "items": { "$ref": "#/components/schemas/CategoryPathNode" }, "type": "array" }, "type": "array", "title": "Category Path", "description": "Full category paths (level 0 → 1 → 2). A product can sit in two trees, hence a list of paths." }, "popularity_score": { "type": "number", "title": "Popularity Score", "description": "Mercadona's internal popularity ranking (undocumented, higher = more popular). Null for products added to the catalog in the last day.", "nullable": true } }, "type": "object", "required": [ "product_id", "name", "availability" ], "title": "ListRow", "description": "Product list row: the card plus barcode, brand, category path and popularity score." }, "ResolvedEan": { "properties": { "input": { "type": "string", "title": "Input", "description": "The EAN the caller sent." }, "resolved": { "type": "string", "title": "Resolved", "description": "Product id the barcode resolved to; null when unknown.", "nullable": true }, "source": { "allOf": [ { "$ref": "#/components/schemas/EanResolutionSource" } ], "description": "`index` (barcode known) or `not_found`." } }, "type": "object", "required": [ "input", "source" ], "title": "ResolvedEan" }, "SearchCategoryNode": { "properties": { "category_id": { "type": "integer", "title": "Category Id", "description": "Category id." }, "name": { "type": "string", "title": "Name", "description": "Category name; null when it cannot be looked up at the moment.", "nullable": true }, "level": { "type": "integer", "title": "Level", "description": "0 / 1 / 2." }, "count": { "type": "integer", "title": "Count", "description": "Matched products under this node, computed over ALL matches (not only the 100 returned)." }, "categories": { "items": { "$ref": "#/components/schemas/SearchCategoryNode" }, "type": "array", "title": "Categories", "description": "Child nodes." } }, "type": "object", "required": [ "category_id", "level", "count" ], "title": "SearchCategoryNode" }, "BrandProductRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode. Always present on /search rows; on other listings it is null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products; house brands are `Hacendado`, `Deliplus`, `Bosque Verde`…).", "nullable": true }, "category_path": { "items": { "items": { "$ref": "#/components/schemas/CategoryPathNode" }, "type": "array" }, "type": "array", "title": "Category Path", "description": "Full category paths (level 0 → 1 → 2). A product can sit in two trees, hence a list of paths." }, "popularity_score": { "type": "number", "title": "Popularity Score", "description": "Mercadona's internal popularity ranking (undocumented, higher = more popular). Null for products added to the catalog in the last day.", "nullable": true }, "category_rank": { "type": "integer", "minimum": 1.0, "title": "Category Rank", "description": "Popularity position of the product inside its own level-1 category (the level-1 node of the first `category_path`) in this warehouse, 1 = most popular; the same whatever the filters, sort or page of the request. Products with equal popularity share a position and the next one is skipped (1, 2, 2, 4). For a store warehouse it is the position in the first hub with a daily catalog snapshot. Null when no daily catalog snapshot ranks the product (e.g. added to the catalog in the last day).", "nullable": true } }, "type": "object", "required": [ "product_id", "name", "availability" ], "title": "BrandProductRow", "description": "List row as served by /brand-products: plus the product's popularity position in its level-1 category." }, "DataSource": { "type": "string", "enum": [ "catalog_index", "live" ], "title": "DataSource" }, "ResolvedWarehouse": { "properties": { "input": { "type": "string", "title": "Input", "description": "What the caller sent: the `postal_code` or the `warehouse` value; null when neither was given.", "nullable": true }, "resolved": { "type": "string", "title": "Resolved", "description": "Warehouse code actually used; null when a postal code is outside Mercadona's delivery area.", "nullable": true }, "source": { "allOf": [ { "$ref": "#/components/schemas/ResolutionSource" } ], "description": "`postal_code` (resolved from the postal code), `param` (caller's warehouse), `default` (neither given → `vlc1`), `not_found` (postal code out of area)." } }, "type": "object", "required": [ "source" ], "title": "ResolvedWarehouse", "description": "Which warehouse answered and why." }, "ResolvedBrands": { "properties": { "input": { "type": "string", "title": "Input", "description": "The `brand` string the caller sent, as sent." }, "resolved": { "items": { "type": "string" }, "type": "array", "title": "Resolved", "description": "Brand names actually filtered on: split on commas, trimmed, de-duplicated, in input order. Exact match — no fuzzy matching; a name that matches nothing simply adds no rows." }, "source": { "allOf": [ { "$ref": "#/components/schemas/BrandResolutionSource" } ], "description": "Always `param` (taken from the request as written).", "default": "param" } }, "type": "object", "required": [ "input", "resolved" ], "title": "ResolvedBrands", "description": "Echo of a comma-separated `brand` OR list (E-08)." }, "CampaignData": { "properties": { "campaign_id": { "type": "string", "title": "Campaign Id", "description": "Echo of `campaign_id`." }, "title": { "type": "string", "title": "Title", "description": "Section title." }, "section_code": { "type": "string", "title": "Section Code", "description": "Mercadona's code for the kind of home section: `PD` price drops, `NA` new arrivals (Novedades), `RE` products that are back (\"Han vuelto\"), `PS` themed carousel, `SN` seasonal campaign; anything else is another kind. Informational only — no endpoint filters on it.", "nullable": true }, "items": { "items": { "$ref": "#/components/schemas/CardRow" }, "type": "array", "title": "Items", "description": "Products of this page (card row + `color_variants`)." }, "total": { "type": "integer", "title": "Total", "description": "Products in the section." }, "page": { "type": "integer", "title": "Page", "description": "Echo of `page`." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Echo of `per_page`." }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "`ceil(total / per_page)`." }, "has_next_page": { "type": "boolean", "title": "Has Next Page", "description": "True while `page < total_pages`." }, "resolved_filters": { "allOf": [ { "$ref": "#/components/schemas/ResolvedFilters" } ], "description": "Warehouse echo." }, "language": { "allOf": [ { "$ref": "#/components/schemas/Language" } ], "description": "Echo of `language`." } }, "type": "object", "required": [ "campaign_id", "title", "total", "page", "per_page", "total_pages", "has_next_page", "resolved_filters", "language" ], "title": "CampaignData" }, "BrandItem": { "properties": { "brand": { "type": "string", "title": "Brand", "description": "Exact brand string — pass it verbatim to `brand=` on other endpoints." }, "products_count": { "type": "integer", "title": "Products Count", "description": "Products of this brand in scope (one warehouse, or distinct products over the hubs)." } }, "type": "object", "required": [ "brand", "products_count" ], "title": "BrandItem" }, "BestsellerRow": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "Mercadona product id as a string (decimal ids like `81241.3` exist)." }, "name": { "type": "string", "title": "Name", "description": "Display name in the requested language." }, "slug": { "type": "string", "title": "Slug", "description": "Path segment of `url`. Not a lookup key: no endpoint accepts it, use `product_id`.", "nullable": true }, "url": { "type": "string", "title": "Url", "description": "Public product page URL on tienda.mercadona.es.", "nullable": true }, "thumbnail": { "type": "string", "title": "Thumbnail", "description": "300 px image URL.", "nullable": true }, "packaging": { "type": "string", "title": "Packaging", "description": "Packaging label, e.g. `Brik`, `Pack-6` (≈ 85–90 % filled).", "nullable": true }, "main_feature": { "type": "string", "title": "Main Feature", "description": "Short marketing line, e.g. `cabello débil y dañado`. Sparse: set on some products only; null otherwise.", "nullable": true }, "is_water": { "type": "boolean", "title": "Is Water", "description": "True for bottled water (counts towards Mercadona's per-order water limit).", "default": false }, "requires_age_check": { "type": "boolean", "title": "Requires Age Check", "description": "Age-restricted product (alcohol etc.).", "default": false }, "category": { "allOf": [ { "$ref": "#/components/schemas/CategoryRef" } ], "description": "Level-0 category of the row.", "nullable": true }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Stock-like state block." }, "price": { "type": "string", "title": "Price", "description": "Selling price as shown in the shop (string, e.g. `4.98`).", "nullable": true }, "price_value": { "type": "number", "title": "Price Value", "description": "Selling price as a float, 2 decimals.", "nullable": true }, "previous_price": { "type": "string", "title": "Previous Price", "description": "Previous (was) price as a string; null when there is no price drop.", "nullable": true }, "previous_price_value": { "type": "number", "title": "Previous Price Value", "description": "Was-price as a float, 2 decimals; null when none.", "nullable": true }, "is_price_drop": { "type": "boolean", "title": "Is Price Drop", "description": "True when `previous_price_value > price_value` (the product is on a price drop).", "default": false }, "unit_price": { "type": "string", "title": "Unit Price", "description": "Shelf-label price per reference unit (e.g. per litre or kilo), string.", "nullable": true }, "unit_price_value": { "type": "number", "title": "Unit Price Value", "description": "Reference price as a float, 2 decimals.", "nullable": true }, "unit_price_format": { "type": "string", "title": "Unit Price Format", "description": "Reference unit: `L`, `kg`, `100 ml`, `ud`, `dz`, `dc`.", "nullable": true }, "bulk_price_value": { "type": "number", "title": "Bulk Price Value", "description": "Price per bulk unit as a float, when Mercadona publishes one.", "nullable": true }, "size_format": { "type": "string", "title": "Size Format", "description": "`l`, `kg` or `ud`.", "nullable": true }, "unit_size": { "type": "number", "title": "Unit Size", "description": "Size of one unit in `size_format`.", "nullable": true }, "is_pack": { "type": "boolean", "title": "Is Pack", "description": "Multi-unit pack.", "default": false }, "pack_size": { "type": "number", "title": "Pack Size", "description": "Pack size (≈ 32 % filled).", "nullable": true }, "total_units": { "type": "integer", "title": "Total Units", "description": "Units in the pack (≈ 44 % filled).", "nullable": true }, "unit_name": { "type": "string", "title": "Unit Name", "description": "Unit noun, e.g. `briks` (≈ 44 % filled).", "nullable": true }, "iva_percent": { "type": "integer", "title": "Iva Percent", "description": "Spanish VAT rate applied: 4, 10 or 21.", "nullable": true }, "approx_size": { "type": "boolean", "title": "Approx Size", "description": "Size is approximate (variable-weight items).", "default": false }, "drained_weight": { "type": "number", "title": "Drained Weight", "description": "Drained weight. Sparse: set on canned goods only (< 1 % of products); null otherwise.", "nullable": true }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency of every price field. Always `EUR`.", "default": "EUR" }, "color_variants": { "items": { "$ref": "#/components/schemas/ColorVariant" }, "type": "array", "title": "Color Variants", "description": "Sibling shades. Rare: only some non-food products (make-up shades) carry them; null otherwise.", "nullable": true }, "warehouse": { "type": "string", "title": "Warehouse", "description": "Warehouse whose assortment and prices this row reflects.", "nullable": true }, "ean": { "type": "string", "title": "Ean", "description": "EAN-13 barcode. Always present on /search rows; on other listings it is null for products added to the catalog in the last day.", "nullable": true }, "brand": { "type": "string", "title": "Brand", "description": "Brand name exactly as Mercadona writes it (null for unbranded fresh products; house brands are `Hacendado`, `Deliplus`, `Bosque Verde`…).", "nullable": true }, "category_path": { "items": { "items": { "$ref": "#/components/schemas/CategoryPathNode" }, "type": "array" }, "type": "array", "title": "Category Path", "description": "Full category paths (level 0 → 1 → 2). A product can sit in two trees, hence a list of paths." }, "popularity_score": { "type": "number", "title": "Popularity Score", "description": "Mercadona's internal popularity ranking (undocumented, higher = more popular). Null for products added to the catalog in the last day.", "nullable": true }, "category_rank": { "type": "integer", "minimum": 1.0, "title": "Category Rank", "description": "Popularity position of the product inside its own level-1 category (the level-1 node of the first `category_path`) in this warehouse, 1 = most popular; the same whatever the filters, sort or page of the request. Products with equal popularity share a position and the next one is skipped (1, 2, 2, 4). For a store warehouse it is the position in the first hub with a daily catalog snapshot. Null when no daily catalog snapshot ranks the product (e.g. added to the catalog in the last day).", "nullable": true }, "rank": { "type": "integer", "minimum": 1.0, "title": "Rank", "description": "1-based position in the popularity ordering of the applied filters, continuous across pages." } }, "type": "object", "required": [ "product_id", "name", "availability", "rank" ], "title": "BestsellerRow" }, "EanResolutionSource": { "type": "string", "enum": [ "index", "not_found" ], "title": "EanResolutionSource" }, "ResolutionSource": { "type": "string", "enum": [ "postal_code", "param", "default", "not_found" ], "title": "ResolutionSource" } } }, "tags": [ { "name": "Drift", "description": "Per-API drift detection — periodic self-calls + assertion suite, cached and exposed via GET /drift/{api}." } ] }