{ "openapi": "3.1.0", "info": { "title": "WizStore Public API — Israeli supermarket price comparison, in one place", "version": "1.0.0", "summary": "Read-only daily supermarket prices, chain and store price indexes in Israel.", "description": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014.\n\nShelf and promotion prices per product and chain, a price index per chain and per store (100 = national median). Updated daily from the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014. The data covers the chains whose files WizStore collects and processes, not necessarily every chain in Israel. Every response carries as_of (the data date), source, coverage and page (the human page to cite). Data is updated once a day, after the daily build (starts 14:00 Israel time, usually done by 14:45). Responses are cached until shortly after the next build — at most 6 h; between 14:00 and 16:00, while the build lands, 10 minutes. The time left is the s-maxage in Cache-Control; browsers keep a response 5 minutes.\n\nPrices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ.\n\nFree and read-only, with an API key: instant self-service sign-up at https://wizbi.store/developers#register. Send it as x-api-key: wzs_… or Authorization: Bearer wzs_…. (?key=wzs_… in the URL is deprecated since 2026-10-08 — URLs are logged.) 1000 calls/day and 60/minute per key; 401 without a key, 429 + Retry-After over the limit. Attribution with a link to https://wizbi.store is required wherever the data is shown. Contact contact@wizbi.ai for higher limits.", "termsOfService": "https://wizbi.store/api-terms", "contact": { "name": "WizStore by WizBI", "url": "https://wizbi.store/developers", "email": "contact@wizbi.ai" } }, "externalDocs": { "description": "Developer guide (Hebrew)", "url": "https://wizbi.store/developers" }, "servers": [ { "url": "https://wizbi.store/api/v1" } ], "security": [ { "apiKey": [] }, { "bearer": [] }, { "apiKeyQuery": [] } ], "paths": { "/products/{code}": { "get": { "operationId": "getProduct", "summary": "Product prices by barcode — summary, per-chain prices, 90-day history", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{6,14}$" }, "example": "7290100687109" } ], "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/basket": { "get": { "operationId": "priceBasketGet", "summary": "Same as POST /basket, as a GET (cacheable): ?city=…&items=item|item|…", "parameters": [ { "name": "city", "in": "query", "required": true, "schema": { "type": "string" }, "example": "חיפה" }, { "name": "items", "in": "query", "required": true, "description": "Items separated by \"|\" (or the parameter repeated), up to 40.", "schema": { "type": "string" }, "example": "חלב תנובה 3%|2 לחם אחיד|ביצים L 12" } ], "responses": { "200": { "description": "Cheapest branches", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "$ref": "#/components/schemas/Basket" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "priceBasket", "summary": "Price a shopping list in every branch of a city — the 5 cheapest branches with coverage", "description": "Items are free-text Hebrew product names (optionally with a quantity: \"2 חלב 3%\", \"במבה x3\") or barcodes, up to 40. Each is matched to one product (returned in items[].matched). Branches carrying at least 85% of the matched items are ranked by effective_total; the rest follow by coverage. Each branch has effective_total (= total), shelf_total and club_total. Also limited to 30 baskets/hour per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "city" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "string", "maxLength": 80 } }, "city": { "type": "string", "description": "City in Hebrew or English, or its slug" } } }, "example": { "items": [ "חלב תנובה 3%", "2 לחם אחיד", "ביצים L 12", "במבה x3", "קוטג׳ 5%" ], "city": "חיפה" } } } }, "responses": { "200": { "description": "Cheapest branches", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "$ref": "#/components/schemas/Basket" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/basket/chains": { "get": { "operationId": "compareBasketByChain", "summary": "A shopping list compared across chains (no city): shelf / effective / club totals per chain", "description": "shelf_total = sum of each chain's median shelf price; effective_total = its lowest price after promotions open to everyone; club_total = the same including club-only promotions. effective/club take each item's lowest price in any of the chain's branches (a best case); the ranking is by shelf_total — use /basket for real branches in one city. POST {\"items\": [...]} also works.", "parameters": [ { "name": "items", "in": "query", "required": true, "description": "Items separated by \"|\", up to 40.", "schema": { "type": "string" }, "example": "חלב תנובה 3%|לחם אחיד|ביצים L 12" } ], "responses": { "200": { "description": "Totals per chain", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "$ref": "#/components/schemas/ChainBasket" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deals": { "get": { "operationId": "listDeals", "summary": "Today's strongest deals (≥10% below the national median shelf price), nationally or for one chain", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string" }, "example": "shufersal" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 60, "default": 20 } } ], "responses": { "200": { "description": "Deals", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "rule": { "type": "string" }, "count": { "type": "integer" }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } } } } } } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/list-link": { "get": { "operationId": "shoppingListLink", "summary": "A link that opens these items as a smart shopping list on the site (created when the person opens it)", "parameters": [ { "name": "items", "in": "query", "required": true, "description": "Items separated by \"|\", up to 40.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The link", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search": { "get": { "operationId": "searchProducts", "summary": "Search products by Hebrew name or barcode (up to 20 results)", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "example": "חלב תנובה" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } ], "responses": { "200": { "description": "Matches, most widely sold first", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chains": { "get": { "operationId": "listChains", "summary": "Supermarket chains with their price index (cheapest first)", "responses": { "200": { "description": "Chains", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "index_note": { "type": "string" }, "methodology": { "type": "string", "format": "uri" }, "chains": { "type": "array", "items": { "$ref": "#/components/schemas/Chain" } } } } } } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cities": { "get": { "operationId": "listCities", "summary": "Cities with stores (slug, Hebrew and English name, store count, best index)", "responses": { "200": { "description": "Cities", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "cities": { "type": "array", "items": { "$ref": "#/components/schemas/City" } } } } } } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cities/{slug}/stores": { "get": { "operationId": "cityStores", "summary": "Stores in a city, cheapest supermarket first (same ranking as the city page: basket total, 60% basket / 85% coverage gate)", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "City slug from /cities (Hebrew or English names are also matched).", "schema": { "type": "string" }, "example": "haifa" } ], "responses": { "200": { "description": "Stores", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "source", "attribution", "data" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date", "description": "Date of the latest price files in the dataset." }, "source": { "type": "string", "example": "WizStore (wizbi.store) — על בסיס קובצי המחירים והמבצעים שרשתות השיווק מחויבות לפרסם לפי חוק קידום התחרות בענף המזון" }, "source_en": { "type": "string", "example": "WizStore (wizbi.store) — based on the price and promotion files Israeli retail chains are required to publish under the Promotion of Competition in the Food Sector Law, 2014" }, "page": { "type": [ "string", "null" ], "format": "uri", "description": "The human page that shows the same numbers — link it when quoting (also attribution.link)." }, "price_fields": { "type": "string", "description": "What shelf / effective / club mean.", "example": "Prices are in ILS. shelf — the regular price the chain publishes for the store, without any promotion. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately. Field names: *_shelf = shelf, *_effective = effective, *club* = club. Prices are as published by the chains; the price at the register may differ." }, "coverage": { "type": [ "object", "null" ], "description": "What the dataset covers on as_of: chains, stores and barcoded products (the same counts as the site).", "properties": { "chains": { "type": "integer" }, "stores": { "type": "integer" }, "products": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "data": { "type": "object", "properties": { "city": { "type": "object" }, "index_note": { "type": "string" }, "count": { "type": "integer" }, "stores": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } } } } } } } }, "401": { "description": "API key missing, invalid or revoked. Free sign-up: https://wizbi.store/developers#register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit reached (1000/day or 60/minute per key). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Required. wzs_ + 32 characters — free at https://wizbi.store/developers#register." }, "bearer": { "type": "http", "scheme": "bearer", "description": "The same key as Authorization: Bearer wzs_…" }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "key", "description": "DEPRECATED (2026-10-08): the same key in the URL. URLs end up in logs — use a header. Still accepted for now; answers carry a Deprecation header." } }, "schemas": { "Attribution": { "type": "object", "properties": { "required": { "type": "boolean" }, "text": { "type": "string" }, "text_en": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "rule": { "type": "string" }, "terms": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string", "description": "Hebrew" }, "message_en": { "type": "string" } } }, "ProductSummary": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "manufacturer": { "type": [ "string", "null" ] }, "chains": { "type": "integer" }, "stores": { "type": "integer" }, "min_shelf": { "type": "number", "description": "ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "median_shelf": { "type": "number", "description": "ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "max_shelf": { "type": "number", "description": "ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "min_effective": { "type": "number", "description": "Lowest effective price. ILS. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default." }, "url": { "type": "string", "format": "uri" } } }, "Product": { "allOf": [ { "$ref": "#/components/schemas/ProductSummary" }, { "type": "object", "properties": { "gtin": { "type": "string" }, "base_unit": { "type": [ "string", "null" ] }, "base_qty": { "type": [ "number", "null" ] }, "median_price_per_base_unit": { "type": [ "number", "null" ] }, "min_effective_club": { "type": [ "number", "null" ], "description": "Lowest price counting club-only promotions too. ILS. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately." }, "pct_on_promo": { "type": [ "number", "null" ] }, "price_as_of": { "type": [ "string", "null" ], "format": "date" }, "per_chain": { "type": "array", "items": { "type": "object", "properties": { "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "stores": { "type": "integer" }, "min_shelf": { "type": "number" }, "median_shelf": { "type": "number" }, "max_shelf": { "type": "number" }, "min_effective": { "type": "number", "description": "ILS. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default." }, "min_club_promo": { "type": [ "number", "null" ], "description": "ILS. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately." }, "stores_on_promo": { "type": [ "integer", "null" ] }, "best_open_promo": { "type": [ "string", "null" ] }, "best_club_promo": { "type": [ "string", "null" ] }, "as_of": { "type": [ "string", "null" ], "format": "date" }, "multibuy": { "type": [ "object", "null" ], "description": "Multi-buy deal (\"2 for ₪22\"): `qty` units for `total`; `unit_price` applies from `qty` units only — min_effective is the single-unit price.", "properties": { "qty": { "type": "integer" }, "total": { "type": "number" }, "unit_price": { "type": "number" }, "text": { "type": [ "string", "null" ] } } }, "multibuy_club": { "type": [ "object", "null" ], "description": "The same, for club members only." } } } }, "history_90d": { "type": "array", "items": { "type": "object", "properties": { "d": { "type": "string", "format": "date" }, "median_shelf": { "type": "number" }, "min_shelf": { "type": "number" } } } } } } ] }, "Basket": { "type": "object", "properties": { "city": { "type": "object", "properties": { "city_slug": { "type": "string" }, "city_name": { "type": "string" }, "city_name_en": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } }, "method": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "qty": { "type": "number" }, "matched": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "median_shelf": { "type": [ "number", "null" ] }, "min_effective": { "type": [ "number", "null" ] }, "url": { "type": "string", "format": "uri" } } } } } }, "matched_items": { "type": "integer" }, "unmatched": { "type": "array", "items": { "type": "string" } }, "stores_in_city_with_items": { "type": "integer" }, "cheapest_stores": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "store_id": { "type": "string" }, "store_name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "total": { "type": "number", "description": "Same as effective_total" }, "effective_total": { "type": "number", "description": "Σ effective price × qty. ILS. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default." }, "shelf_total": { "type": [ "number", "null" ], "description": "Σ shelf price × qty. ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "club_total": { "type": [ "number", "null" ], "description": "Σ (club price where the store has one, else effective) × qty. ILS. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately." }, "found": { "type": "integer" }, "of": { "type": "integer" }, "coverage": { "type": "number" }, "full_coverage_ranked": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" }, "order_online_url": { "type": [ "string", "null" ], "format": "uri", "description": "Opens the chain’s own online store (Stor.ai storefronts) with the list in its cart popup, on this store’s online branch when known; null when the chain has none. The person adds to cart, logs in and pays there." } } } } } }, "ChainBasket": { "type": "object", "properties": { "method": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "matched_items": { "type": "integer" }, "unmatched": { "type": "array", "items": { "type": "string" } }, "cheapest_complete_chain": { "type": [ "object", "null" ] }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "found": { "type": "integer" }, "of": { "type": "integer" }, "complete": { "type": "boolean" }, "shelf_total": { "type": [ "number", "null" ], "description": "Σ the chain's median shelf price × qty. ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "effective_total": { "type": [ "number", "null" ], "description": "Σ the chain's lowest effective price × qty. ILS. effective — the lower of the shelf price and a promotion open to every shopper, per unit (\"3 for 30\" = 10 per unit). This is the price the site compares by default." }, "club_total": { "type": [ "number", "null" ], "description": "Same, counting club-only promotions. ILS. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately." }, "missing": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" } } } }, "open_as_list": { "type": "string", "format": "uri" } } }, "Deal": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "deal_price": { "type": "number", "description": "ILS per unit" }, "chain_shelf": { "type": [ "number", "null" ], "description": "ILS. shelf — the regular price the chain publishes for the store, without any promotion." }, "national_median_shelf": { "type": [ "number", "null" ] }, "pct_below_median": { "type": [ "number", "null" ] }, "club_only": { "type": "boolean", "description": "ILS. club — a promotion limited to the chain's loyalty-club members or card holders. Never folded into effective; shown separately." }, "description": { "type": [ "string", "null" ] }, "ends_on": { "type": [ "string", "null" ], "format": "date" }, "url": { "type": "string", "format": "uri" } } }, "Chain": { "type": "object", "properties": { "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "stores": { "type": "integer" }, "cities": { "type": "integer" }, "price_index": { "type": [ "number", "null" ], "description": "100 = national median; below 100 is cheaper" }, "effective_index": { "type": [ "number", "null" ], "description": "Same, after promotions open to everyone" }, "in_rankings": { "type": "boolean", "description": "false when the chain's data is not comparable today (a partial price file, too narrow a range): do not rank it or call it the cheapest / dearest" }, "data_warning": { "type": "string", "description": "Why in_rankings is false (Hebrew), present only then" }, "as_of": { "type": [ "string", "null" ], "format": "date" }, "url": { "type": "string", "format": "uri" } } }, "City": { "type": "object", "properties": { "city_slug": { "type": "string" }, "city_name": { "type": "string" }, "city_name_en": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "stores": { "type": "integer" }, "chains": { "type": "integer" }, "best_price_index": { "type": [ "number", "null" ] }, "url": { "type": "string", "format": "uri" } } }, "Store": { "type": "object", "properties": { "chain_key": { "type": "string" }, "chain_name": { "type": "string" }, "store_id": { "type": "string" }, "store_name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "price_index": { "type": [ "number", "null" ] }, "effective_index": { "type": [ "number", "null" ] }, "items": { "type": "integer" }, "items_on_promo": { "type": "integer" }, "as_of": { "type": [ "string", "null" ], "format": "date" }, "url": { "type": "string", "format": "uri" } } } } } }