GroceryPulse Canada

Plans a grocery order from a shopping list as the shopper wrote it, in a covered Canadian city. Use when a shopper asks where their list is cheapest or wants to buy groceries online. Takes the list as text (English or French, quantities included, up to 60 lines), the city or the first three characters of a postal code inside it and, optionally, the stores the shopper uses. Returns each line as exact, closest (a different size, variant or brand: not priced and in no total) or not tracked; per-store totals with coverage and price dates; a cheapest store only when every compared item is priced at two or more chains with a clear lead (or, when the only obstacle is a pack item whose count no store's listing gives, a store labelled cheapest for the other lines, with those lines listed apart), otherwise the reason; per-item links to each store's own product page or search; and interpretation notes that state what the result does and does not cover. Read-only: it never orders, adds to a cart, saves a list or contacts a store.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "minLength": 1,
      "maxLength": 3000,
      "description": "The shopper's grocery list exactly as they wrote it, one item per line (or comma-separated), English or French, with quantities if they gave them: \"2L milk\", \"dozen eggs\", \"3 lbs lean ground beef\", \"oeufs\"."
    },
    "city": {
      "type": "string",
      "maxLength": 60,
      "description": "The covered Canadian city whose chain prices are compared (the price market): its English or French name, or its slug. Give this or postalCode."
    },
    "postalCode": {
      "type": "string",
      "maxLength": 10,
      "description": "The first three characters of a Canadian postal code (the forward sortation area, for example K1P), used only to choose the covered city. Areas outside the covered cities are refused, never moved to the nearest one. A full postal code is accepted; only its first three characters are read."
    },
    "stores": {
      "type": "array",
      "maxItems": 40,
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "description": "Optional: only the stores the shopper is willing to use (names like \"No Frills\" or catalogue keys). Omit to compare every tracked chain in the city."
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "fr"
      ],
      "description": "Language for item names and store links. Default en."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Lists GroceryPulse's configured Canadian cities, canonical reference items with their ids, quantity units, known chains and checkout eligibility holds: the ids that compare_grocery_list takes. Configured coverage is not current availability or coverage of every nearby branch. Each item is one product at one package size (its name and referenceSize); a different size, variant or brand is a different product.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Compares current public chain prices for a list of catalogue item ids (from get_grocery_catalog) and quantities in one supported Canadian city; plan_grocery_order is the form that takes a list in the shopper's own words. A lowest-chain recommendation requires fresh full requested coverage at two eligible chains with no close call or package/reference-size reversal. Results keep missing items, exclusions, price dates, scope and source links, and each chain includes plain per-item storeLinks to its own product page or search, with the price date used. Each id is one product at its catalogue size (for example 4 L milk); a different size, variant or brand is a different product. Chain medians are not branch stock or guaranteed checkout quotes. Read-only: it does not buy, save a list, send email or access licensed or private data.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "enum": [
        "vancouver",
        "victoria",
        "calgary",
        "edmonton",
        "saskatoon",
        "regina",
        "winnipeg",
        "toronto",
        "ottawa",
        "montreal",
        "quebec-city",
        "moncton",
        "fredericton",
        "halifax",
        "charlottetown",
        "st-johns"
      ]
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "description": "IDs must be unique. Each id is one product at one package size (its catalogue name and referenceSize); a different size, variant or brand is a different product (for example, the catalogue's 4 L milk is not 2 L milk).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "qty"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "enum": [
              1,
              2,
              3,
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19,
              20,
              21,
              22,
              23,
              24,
              25,
              26,
              27,
              28,
              29,
              30,
              31,
              32,
              33,
              34,
              35,
              36,
              37,
              38,
              39,
              40,
              41,
              42,
              43,
              44,
              45,
              46,
              47,
              48,
              49,
              50
            ]
          },
          "qty": {
            "type": "number",
            "minimum": 0.25,
            "maximum": 20,
            "multipleOf": 0.25
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "id": {
                  "enum": [
                    7,
                    8,
                    9,
                    11,
                    18,
                    21,
                    27,
                    50
                  ]
                }
              }
            },
            "then": {
              "properties": {
                "qty": {
                  "type": "number",
                  "minimum": 0.25,
                  "maximum": 10,
                  "multipleOf": 0.25
                }
              }
            },
            "else": {
              "properties": {
                "qty": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 20
                }
              }
            }
          }
        ]
      }
    },
    "stores": {
      "type": "array",
      "maxItems": 40,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "atlanticsuperstore",
          "dominion",
          "farmboy",
          "foodbasics",
          "foodland",
          "fortinos",
          "freshco",
          "gianttiger",
          "iga",
          "loblaws",
          "maxi",
          "metro",
          "nofrills",
          "provigo",
          "safeway",
          "saveonfoods",
          "sobeys",
          "superc",
          "superstore",
          "thriftyfoods",
          "valumart",
          "voila",
          "walmart",
          "wholesaleclub",
          "yourindependentgrocer",
          "zehrs"
        ]
      },
      "default": []
    }
  },
  "required": [
    "city",
    "items"
  ],
  "additionalProperties": false
}