{ "openapi": "3.1.0", "info": { "title": "Foodiepedia Israeli Supermarket Prices API", "version": "1.0.0", "description": "Daily shelf prices from 31 Israeli supermarket chains, matched by barcode. Shelf prices, one branch per chain in the Sharon region of Israel (the default comparison), plus one branch per chain in four more regions. Club deals, coupons and multi-buy promotions are not included. Checked twice a day, 07:30 and 15:30 Israel time.\n\nAttribution required: \"Source: Foodiepedia (foodiepedia.co.il), from the Israeli chains' price-transparency files\" (cite and link).\n\nPrices are collected automatically from files the chains publish and may contain errors (in the chains' files or in our processing). The price at the checkout is what counts. Not financial advice. Rows flagged suspect=true have an abnormal gap between chains (often a pack priced as a single unit) and must not be quoted as savings.", "contact": { "email": "foodiepedias@gmail.com", "url": "https://foodiepedia.co.il" }, "x-guidance": "Israeli supermarket shelf prices by barcode. Find a product with GET /api/v1/prices/search?q= (free, top 5) or GET /api/v1/prices/search-full?q=... (paid, up to 25 with the price range). Then GET /api/v1/prices/product/{barcode} for every chain's price, or GET /api/v1/prices/basket?items=:,... for where a whole list is cheapest. GET /api/v1/prices/chains ranks the chains. Pay per call with x402 (USDC on Base) or send an API key. Always cite foodiepedia.co.il and say when prices were checked (checked_at).", "license": { "name": "cite and link", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://foodiepedia.co.il" } ], "paths": { "/api/v1/prices/search": { "get": { "operationId": "searchProducts", "summary": "Search products by Hebrew name, brand or barcode (free: top 5, cheapest price; with a key: up to 25, full price range)", "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "example": "במבה" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "description": "Matching products. Free: barcode, name, size, chain_count, cheapest_price, cheapest_chains, url, attribution, upgrade. With a key: also lowest/highest price and up to 25 results.", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } } }, "/api/v1/prices/search-full": { "get": { "operationId": "searchProductsFull", "summary": "Full product search: up to 25 matches with the lowest and highest price and the cheapest chains (x402 or API key)", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "example": "במבה" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25 } } ], "responses": { "200": { "description": "Up to 25 matching products with the price range and cheapest chains", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "402": { "description": "API key or payment required. The body explains what the full answer contains, a teaser computed from real data, the plans, and how to get a free trial key instantly. It is also a standard x402 offer (x402Version, accepts; v2 terms in the PAYMENT-REQUIRED header): pay per request in USDC on Base (search $0.01, product $0.02, chains $0.02, basket $0.05) and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "full_answer_contains": { "type": "string" }, "teaser": { "type": [ "object", "null" ] }, "attribution": { "type": "object" }, "upgrade": { "type": "object" } } } } } }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } } }, "/api/v1/prices/product/{barcode}": { "get": { "operationId": "getProductPrices", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" } }, "summary": "A product's price in every chain, cheapest first (API key)", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "barcode", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{6,14}$" }, "example": "7290100687109" }, { "name": "history", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Include recorded price changes" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "md" ] }, "description": "Markdown instead of JSON" } ], "responses": { "200": { "description": "Product, summary, per-chain prices with checked_at", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } }, "text/markdown": { "schema": { "type": "string" } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "402": { "description": "API key or payment required. The body explains what the full answer contains, a teaser computed from real data, the plans, and how to get a free trial key instantly. It is also a standard x402 offer (x402Version, accepts; v2 terms in the PAYMENT-REQUIRED header): pay per request in USDC on Base (search $0.01, product $0.02, chains $0.02, basket $0.05) and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "full_answer_contains": { "type": "string" }, "teaser": { "type": [ "object", "null" ] }, "attribution": { "type": "object" }, "upgrade": { "type": "object" } } } } } }, "403": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } } }, "/api/v1/prices/basket": { "get": { "operationId": "compareBasketGet", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" } }, "summary": "Where a shopping list is cheapest (items as barcode:qty, comma separated; API key)", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "items", "in": "query", "required": true, "schema": { "type": "string" }, "example": "7290000042435:2,7290100687109" } ], "responses": { "200": { "description": "Per-chain totals, cheapest chain, best two-chain split", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "402": { "description": "API key or payment required. The body explains what the full answer contains, a teaser computed from real data, the plans, and how to get a free trial key instantly. It is also a standard x402 offer (x402Version, accepts; v2 terms in the PAYMENT-REQUIRED header): pay per request in USDC on Base (search $0.01, product $0.02, chains $0.02, basket $0.05) and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "full_answer_contains": { "type": "string" }, "teaser": { "type": [ "object", "null" ] }, "attribution": { "type": "object" }, "upgrade": { "type": "object" } } } } } }, "403": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } }, "post": { "operationId": "compareBasket", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" } }, "summary": "Where a shopping list is cheapest (API key)", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 60, "items": { "type": "object", "required": [ "barcode" ], "properties": { "barcode": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 50 } } } } } } } } }, "responses": { "200": { "description": "Per-chain totals, cheapest chain, best two-chain split", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "402": { "description": "API key or payment required. The body explains what the full answer contains, a teaser computed from real data, the plans, and how to get a free trial key instantly. It is also a standard x402 offer (x402Version, accepts; v2 terms in the PAYMENT-REQUIRED header): pay per request in USDC on Base (search $0.01, product $0.02, chains $0.02, basket $0.05) and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "full_answer_contains": { "type": "string" }, "teaser": { "type": [ "object", "null" ] }, "attribution": { "type": "object" }, "upgrade": { "type": "object" } } } } } }, "403": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } } }, "/api/v1/prices/chains": { "get": { "operationId": "rankChains", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" } }, "summary": "Chains ranked by how much more they charge than the cheapest price (API key)", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "responses": { "200": { "description": "Ranking", "content": { "application/json": { "schema": { "type": "object", "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs.", "properties": { "checked_at": { "type": "string" }, "currency": { "type": "string" }, "source": { "type": "object" }, "attribution": { "type": "object" }, "disclaimer": { "type": "string" } } } } } }, "401": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "402": { "description": "API key or payment required. The body explains what the full answer contains, a teaser computed from real data, the plans, and how to get a free trial key instantly. It is also a standard x402 offer (x402Version, accepts; v2 terms in the PAYMENT-REQUIRED header): pay per request in USDC on Base (search $0.01, product $0.02, chains $0.02, basket $0.05) and retry with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2).", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "full_answer_contains": { "type": "string" }, "teaser": { "type": [ "object", "null" ] }, "attribution": { "type": "object" }, "upgrade": { "type": "object" } } } } } }, "403": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" }, "429": { "description": "Invalid (401), suspended or expired (403) key, or quota used up (429)" } } } }, "/api/v1/keys/trial": { "post": { "operationId": "getTrialKey", "summary": "Get a free trial API key instantly (50 requests, 14 days; one per email, one per IP per day)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "The key (shown once), its expiry and how to send it" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/pricing": { "get": { "operationId": "getPricing", "summary": "Plans, limits, authentication, trial and terms (machine-readable)", "security": [], "responses": { "200": { "description": "Pricing", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: Authorization: Bearer fp_live_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } }