{
  "openapi": "3.1.0",
  "info": {
    "title": "Foodiepedia Israeli Supermarket Prices API",
    "version": "1.0.0",
    "description": "Daily shelf prices from 10 Israeli supermarket chains, matched by barcode. Shelf prices, one branch per chain in the Sharon region of Israel. 10 chains. 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\" (CC BY 4.0).\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"
    },
    "license": {
      "name": "CC BY 4.0",
      "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",
        "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 with lowest/highest price",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs."
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prices/product/{barcode}": {
      "get": {
        "operationId": "getProductPrices",
        "summary": "A product's price in every chain, cheapest first",
        "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."
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prices/basket": {
      "get": {
        "operationId": "compareBasketGet",
        "summary": "Where a shopping list is cheapest (items as barcode:qty, comma separated)",
        "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."
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "compareBasket",
        "summary": "Where a shopping list is cheapest",
        "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."
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/prices/chains": {
      "get": {
        "operationId": "rankChains",
        "summary": "Chains ranked by how much more they charge than the cheapest price",
        "responses": {
          "200": {
            "description": "Ranking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Every response: checked_at, currency, source, attribution, disclaimer, docs."
                }
              }
            }
          }
        }
      }
    }
  }
}