Menu

    Specials Feed API

    Supermarket offers in Australia and New Zealand for app builders: every special, half price, multibuy and member price at the major grocery retailers, by state or region, updated daily, with a weekly bulk drop and history from the start date.

    Prices, offers and product details are read daily from each retailer's public website. Every offer says which of its fields were measured and which were inferred, and lists the fields it lacks.

    • Retailers, Australia: Coles, Woolworths, IGA, ALDI. History from 29 September 2026.
    • Retailers, New Zealand: Woolworths NZ, New World, PAK'nSAVE. History from 10 October 2026.
    • Delivery: a JSON API (daily changes or full queries), and weekly CSV and Parquet drops.
    • Machine-readable spec: GET /api/feed/v1/openapi.json.

    Contents: Quick start · Update times · Freshness and polling · Endpoints · Field dictionary · Offer types · Measured and inferred · Dates · Upcoming offers · Weekly drops · Keys and limits · Coverage and known gaps · Examples

    Quick start

    Base URL: https://app.cannonballdata.com/api/feed/v1

    Send your key in the X-Api-Key header (or Authorization: Bearer <key>):

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" \
      "https://app.cannonballdata.com/api/feed/v1/offers?chain=coles&state=NSW&offer_type=half_price&limit=2"

    A sync is two calls: the first with a start time (within the last 8 days), then every 15 minutes with the cursor the last call returned (and its ETag, so a poll with nothing new costs nothing: see Freshness and polling).

    # The first call (start from the weekly drop for everything older: see Paging and history)
    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/offers/changes?since=2026-11-05T00:00:00Z"
    # Every 15 minutes after: keep calling with next_cursor until has_more is false, then keep the last next_cursor (and ETag)
    curl -s -H "X-Api-Key: $CANNONBALL_KEY" -H "If-None-Match: $ETAG" "https://app.cannonballdata.com/api/feed/v1/offers/changes?cursor=$CURSOR"

    Paging and history

    • Cursors (next_cursor) are signed, belong to the key that was given them and to the endpoint and sort that made them, and expire: a day for /offers, 8 days for /offers/changes. Every /offers/changes answer gives a fresh cursor, so a daily sync never sees one expire. A cursor that was changed, made by hand or used with another key answers 400 bad_cursor; an expired one 400 cursor_expired: start the list again, or the sync with since= (the last change.at you stored).
    • How far back one call reaches: /offers/changes?since= the last 8 days; on /offers, since= and active_on the last 31 days, and ended offers (status=ended or all, and /products/{id}) those last seen in the last 31 days (a plan with more history reaches all of it: 90 days, or everything since the start). Older answers 400 window_too_old, and so does an active_on before your plan's own window (Starter: 14 days), rather than an answer missing offers. The whole history is in the backfill drop (/drops?kind=backfill, Pro), and the weekly drop's active file is the starting point for a new sync (Growth, Pro): load it, then call /offers/changes?since=<the drop's created_at>. Without drops (Starter), page through /offers for the current offers, then call /offers/changes?since=<that answer's as_of>. A trial key counts back from the end of its data_until day.

    Update times

    All times are Brisbane time (AEST, UTC+10, no daylight saving). Sydney and Melbourne are one hour ahead from October to April.

    WhatWhen
    A day's readsEach retailer's prices and specials are read first thing (from 03:15 Sydney time), then stock and ranging through the day.
    Same-day update (API)Not switched on yet. Until it is, offers change once a day, with the nightly update: a Wednesday changeover at Coles and Woolworths is in the API by Thursday morning (07:00 Brisbane at the latest). Once it is on, a retailer's offers will be updated within about 30-60 minutes of its read, and data_freshness will say source: fast.
    Nightly update (API)The whole day is rebuilt the next morning, by 07:00 Brisbane at the latest, and is the record: where it differs from the same-day update (a store read later in the day), the offer changes, or a same-day offer it does not confirm ends with end_reason: withdrawn. Each change appears in /offers/changes once.
    New weekly specialsColes, Woolworths, IGA and ALDI change their specials on Wednesday; Woolworths NZ, New World and PAK'nSAVE on Monday.
    Catalogue (next week's specials)Coles and Woolworths publish next week's catalogue on Monday afternoon. Its offers reach the API with the nightly update after we read it (usually by Wednesday 07:00 Brisbane, around when they start); until midnight on their start date in each state's own time zone they are upcoming, then live.
    Weekly dropCut from Wednesday's read, ready on Thursday by 07:00 Brisbane (08:00 Sydney in daylight saving). It holds that week's specials (Wednesday to Tuesday).
    Upcoming ALDI Special BuysListed 1 to 2 weeks before their on-sale date, refreshed daily.

    Endpoints

    Method and pathWhat it returns
    GET /offersOffers, filtered, paged by cursor. Live offers unless you ask for others.
    GET /offers/changesOffers that are new, changed or ended since your cursor (or since time), oldest change first: the sync. Poll every 15 minutes with If-None-Match.
    GET /products/{id}One product and its offers, newest first. id is <retailer>:<retailer code>, for example coles:1000051.
    GET /coveragePer retailer: days expected, days read and the days not read (completeness_percent = days read / days expected), products, offers, field completeness (sale_price_measured: offers with a sale price read at one or more stores), and the share of store prices read directly.
    GET /dropsWeekly and backfill drops, each file a download link for your key, valid for 15 minutes.
    GET /openapi.jsonThe OpenAPI 3.1 description. No key needed.

    /offers filters

    ParameterMeaning
    countryAU or NZ. Default: every country your key covers.
    chainComma-separated: coles, woolworths, iga, aldi, woolworths_nz, newworld, paknsave.
    stateComma-separated location codes: NSW, VIC, QLD, SA, WA, TAS, NT, ACT; New Zealand regions as ISO codes (NZ-AUK Auckland, NZ-WGN Wellington, NZ-CAN Canterbury...).
    statuslive (default), upcoming, ended or all.
    active_onYYYY-MM-DD: offers running on that day (any status). Up to 31 days back, and within your plan's history (Starter: 14 days).
    offer_typeComma-separated offer types.
    sourceshelf or catalogue (see Upcoming offers).
    gtinA barcode.
    productA product id (coles:1000051) or a retailer code.
    sinceISO 8601 time: only offers changed after it. Up to 31 days back.
    limit1 to 1,000. Default 500.
    sortquality (default) or id. quality: the strongest evidence first (the offer type from the retailer's label, the sale price read at the stores and a normal price known; then labelled offers with a normal price; then other labelled offers; promotion_label_missing last), then in a fixed order (the same on every call). id: by id only.
    cursornext_cursor from the previous page (keep the same sort; valid for a day, for your key only).

    Every list answer is { "data": [...], "next_cursor": "...", "has_more": true, "as_of": "...", "data_freshness": {...} }. Keep calling with cursor=<next_cursor> while has_more is true. as_of and data_freshness are described under Freshness and polling.

    Each endpoint takes only its own parameters: /offers the ones above; /offers/changes since, cursor, limit, chain and country; /coverage country; /drops kind and country; /products/{id} none. Any other parameter answers 400 unknown_parameter (so a typo such as retailer=coles fails instead of returning every retailer), and a parameter given twice answers 400 repeated_parameter (lists are comma-separated: chain=coles,iga).

    Field dictionary

    One offer is one product, at one retailer, in one location (an Australian state or a New Zealand region), for an unbroken run of days on the same deal. Money is integer cents in the offer's currency (AUD or NZD). Never add or compare amounts across currencies.

    FieldMeaning
    idStable offer id: <retailer>:<location>:<retailer code>:<first day>. It never changes for the life of the offer.
    statusupcoming (announced, not started), live, or ended, as of the moment you ask, in the offer location's own time zone: an announced offer is live from midnight on its start date there (Perth three hours after Sydney) and ended after its last day, with no update needed.
    sourceshelf: read from the retailer's website. catalogue: announced ahead in the retailer's weekly catalogue.
    retailer.id, retailer.name, retailer.siteThe retailer, and the website the offer was read from (coles.com.au...).
    country, currencyAU/AUD or NZ/NZD.
    location.type, location.codestate (AU), region (NZ) or national, and its code.
    location.nationalTrue when the product is on the offer in every location where the retailer prices it that day.
    location.scopeWithin the location: all_stores (95% or more of the stores pricing the product), most_stores (half or more), some_stores (fewer: common at IGA, where each store sets its own specials).
    location.stores_on_offer, stores_priced, stores_measuredStores on the offer, stores with any price for the product, and stores whose price was read directly that day (0 for a catalogue offer or an announced ALDI Special Buy).
    product.id<retailer>:<retailer code>.
    product.retailer_codeThe retailer's own product number.
    product.gtin, product.gtin_sourceThe barcode. retailer: the retailer publishes it. matched: the retailer publishes none, and the barcode comes from the identical product at another retailer in the same country (never the retailer's own claim). missing: none.
    product.name, brand, sizeAs the retailer shows them.
    offer.type, type_basis, type_confidenceSee Offer types.
    offer.advertisedThe deal in words: Half price, 40% off, Save $1.50, 2 for $5.00, Member price.
    offer.retailer_labelThe retailer's own offer code, unchanged (`SPECIALMULTI_SAVE, TPR40%_OFF`).
    offer.multibuyFor multibuys: quantity, price_cents (for the quantity) and price_each_cents.
    prices.sale_centsThe shelf price during the offer. For a multibuy it is the single-item price (the deal is in offer.multibuy). For a member price, the members' price the retailer prints on the tag ("Club price $4.99"); normal_cents is then the shelf price everyone else pays. Where only some stores in the location are on the offer: the retailer's tag price at those stores, where we read one, else the lowest price in the location (inferred).
    prices.normal_cents, normal_basisThe "was" price the retailer shows (measured; where only some stores are on the offer, the was price on their tag, else on the retailer's label, inferred). Where none is shown, the last shelf price seen in the week before the offer began (inferred), or null (missing).
    prices.unit_cents, unit_per, unit_basisSale price per unit. unit_per is a string: <n><g, kg, mL, L or m>, each or <n> each; the common ones are 100g, 1kg, 100mL, 1L, each, 1m, 10g, 10mL and 100 each, and rarely the retailer's own words (100 sheets). Compare unit prices only with the same unit_per. measured: the retailer's own unit price from its tag (or catalogue), per the unit it uses. inferred: calculated by us from the pack size (100g, 100mL, each or 1m), or the retailer's unit price scaled to a member price.
    prices.discount_cents, discount_percentNormal minus sale, and as a percentage of normal. Null without a normal price.
    dates.first_seen, last_seenThe first and last day the offer was seen on the retailer's website (dates_basis: observed).
    dates.expected_end, expected_end_basisWhen the offer is expected to end: the retailer's own end date (announced) where published, else the last day of the retailer's promo week (inferred; Tuesday in Australia, Sunday in New Zealand).
    dates.announced_start, announced_endStart and end dates the retailer published, where it did.
    dates.ended_on, end_reasonThe day the offer was first seen gone, and why: ended (back to the normal price), replaced (a different deal on the same product), not_seen (not read for over a week), withdrawn (an announced offer that never started, or a same-day offer the nightly update did not confirm).
    dates.starts_at, ends_at, ends_at_basis, time_zoneThe offer's start and end as times (ISO 8601 with the local offset, e.g. 2026-11-11T00:00:00+08:00), at midnight in the location's time zone (time_zone, e.g. Australia/Perth). starts_at: the announced start, else the first day seen. ends_at is exclusive (the first moment it is no longer on): the day it was seen ended (observed), else the day after the announced end (announced), else the day after the expected end (inferred).
    capture.source_site, first_seen_at, last_seen_atThe site read, and when the price was first and last read (UTC).
    change.type, day, atThe offer's last change: new, changed (status, price, type, scope or announced dates moved; for a catalogue offer or an ALDI Special Buy, also the sale price's basis) or ended, the read day it happened and when it was published to the API (at never goes back: a change published later always has a later at).
    gapsThe fields this offer lacks, for example ["gtin", "announced_end"].
    refYour reference for this row: quote it (with the id) when you ask us about an offer. It is specific to your key.

    Offer types

    Each offer gets exactly one type. The checks run in this order; the first that applies wins.

    Orderoffer.typeRuletype_basis
    1multibuyThe retailer shows a quantity deal, such as "2 for $5". A multibuy is never counted as half price, even when its per-item price works out at half. Terms that cost more than the quantity at the offer's own sale price are stale and left out (the offer is typed by its label).measured
    2member_priceA loyalty members' price: New World Clubcard, Woolworths NZ member price.measured
    3clearanceMarked clearance or "while stocks last".measured
    4half_priceThe retailer's label says half price; or, for any other offer showing a was price, the sale price is at most half of it, allowing 1 cent for rounding (the row's own sale_cents and normal_cents).measured (label) or inferred (prices)
    5better_than_half_priceThe retailer's label says better than half price (IGA, Woolworths NZ). Kept apart so you can merge it with half price or not.measured
    6discountAny other price reduction: a special, a percentage off, "save $X". offer.advertised says which.measured
    7everyday_lowAn everyday low or lowered-for-good price badge (Coles Everyday, ALDI Lower Prices, Woolworths NZ Low Price) with no was price. Not a promotion; it is listed so you can show it.measured
    8special_buyAn ALDI Special Buy, announced ahead with its on-sale date.measured
    9promotion_label_missingThe retailer flags the product as on offer, but no label, was price or multibuy is known for it. Usually an offer that was already running when collection began.inferred

    type_confidence is 1 when the retailer's own words decide the type, 0.9 when a label decides it without terms or the numbers decide half price, and 0.5 for promotion_label_missing.

    Online-only offers (an offer for online orders only, with no change at the store) are not offers in this feed. Badges such as "New" and loyalty-points badges are never offers.

    Measured and inferred

    Every price field has a _basis:

    • measured: read directly from the retailer that day. For sale_cents: read at one or more of the location's stores; location.stores_measured says how many, and the other stores on the offer took that price (Coles prices are read at a representative store in each pricing zone, Woolworths at a set of stores with the others on the online price, ALDI at representative stores per region; IGA, Woolworths NZ, New World and PAK'nSAVE at every store). A measured price is not a claim about any one store. For normal_cents: the retailer's own was price.
    • announced (sale_cents only): the price in the retailer's catalogue or ALDI's Special Buys list, read at no store (stores_measured 0): catalogue offers (source: catalogue) and ALDI Special Buys (offer.type: special_buy).
    • inferred: no store in the location was read that day, or we worked the value out: a normal price that is the last shelf price before the offer, a unit price calculated from the pack size (where the retailer prints its own unit price for the offer's price, that is used and measured).
    • missing: not available; the value is null.

    A shelf offer's sale_basis follows which stores were read that day, so it can move from day to day; that alone is not a change in /offers/changes. location.stores_measured against stores_priced shows how much of a location was read directly. /coverage gives each retailer's share of offers with a measured sale price (fields_percent.sale_price_measured) and, per store, the share of store prices read directly (store_prices_measured_percent) over the whole history.

    Dates

    Offer dates are observed: first_seen is the first day we saw the offer on the retailer's site, last_seen the last. Retailers change specials overnight and we read during the day, so first_seen is the offer's first day unless a read was missed (see days_not_read in /coverage). An offer already running on the start date has first_seen on the start date; its true start is earlier.

    expected_end is inferred from the retailer's promo week unless the retailer published an end date. IGA, New World and PAK'nSAVE print an end date on many offers ("Special $9.99 until 2026-11-08"): it is given as announced_end, and expected_end takes it (expected_end_basis: announced). When an offer is not seen for more than 7 days it is closed with end_reason: not_seen.

    Freshness and polling

    Recommended: poll /offers/changes every 15 minutes with the cursor and the ETag from your last call. Until the same-day update is switched on, offers change once a day, with the nightly update (by 07:00 Brisbane), so most polls are free.

    • ETag. /offers and /offers/changes answer with an ETag. Send it back as If-None-Match: when nothing was published since (and no offer's status moved at a local midnight), the answer is 304 Not Modified with no body and counts no rows. It still counts as a request against the per-minute limit.
    • Cursor or time. next_cursor continues exactly after the last change you received. Or pass the last answer's as_of as the next since: as_of is the time of the latest publish, and every change published after it has a later change.at. Either way you get each change once, with no gaps.
    • One feed, two updates (once the same-day update is on). The same-day update and the nightly update publish into the same offers. An offer the same-day update published appears once as new; when the nightly update agrees, it does not appear again; when it differs, it appears again as changed (or as ended with end_reason: withdrawn if the day did not confirm it at all).
    • as_of (every list answer, and /coverage): when the offers you are reading were last published.
    • data_freshness (per retailer, in list answers for the retailers asked and in each /coverage entry): source (fast: the same-day update of today's read so far; nightly: a whole day), day (the read day, Sydney), last_read_at (the newest price read in it) and published_at.

    Webhooks are not offered yet: polling /offers/changes with If-None-Match every 15 minutes gets the same changes within 15 minutes of publishing.

    Upcoming offers

    Offers announced before they start have status: upcoming and dates.announced_start.

    • ALDI Special Buys (offer.type: special_buy) are listed 1 to 2 weeks before their on-sale date, with price (sale_basis: announced). They are live from the on-sale date for 14 days (while stocks last).
    • Catalogue offers (source: catalogue): the Coles and Woolworths weekly catalogue, read when the retailer publishes it (Monday afternoon) for the week starting Wednesday, with announced start and end dates, the catalogue price (sale_basis: announced; for a multibuy, the one-item price we work out from the deal, inferred), the was price and the retailer's unit price as printed (measured). One offer per state that lists the catalogue and per product the offer covers; offer.retailer_label is the catalogue's own wording ("1/2 Price, Save $11.50"). Items in the catalogue with no offer wording are left out. They reach /offers and /offers/changes with the nightly update after we read the catalogue (usually by Wednesday 07:00 Brisbane), as upcoming until midnight on the start date in each state's time zone (dates.starts_at), then live.

    Each step (announced, started, ended or withdrawn) appears in /offers/changes.

    Weekly drops

    GET /drops lists every drop your key may download. Each drop has CSV and Parquet files with the offer's fields, flattened, under the stored names (money in cents: sale_c, normal_c...), stores_measured (empty in drops cut before it was added, November 2026), and ref, as in the API. The files leave out retailer.site, gaps and the time of change.at (they have changed_day):

    • Weekly, per country: active (every live and upcoming offer) and changes (offers new, changed or ended in the 7 days to the drop day). Cut from Wednesday's read, ready Thursday by 07:00 Brisbane time.
    • Backfill, per country: the whole history from the start date, one file per retailer and month (history-coles-2026-10). The API itself reaches back 31 days (see Paging and history).

    Download links are made for your key: each is valid for 15 minutes, works only while your key is active, and each download counts as a request against your key's limits. Each file downloads at most 5 times a day (CSV and Parquet together, counted across every key of your plan, Brisbane day; past that 429 download_limit_day until midnight). Ask /drops again for fresh ones.

    Keys and limits

    • One key per customer, scoped to the countries in your plan (AU, NZ or both). Asking for a country outside it answers 403.
    • Getting a key: ask us through the contact form and we'll set one up for your countries.
    • Default limits (a day runs midnight to midnight Brisbane time): 60 requests a minute and 10,000 requests a day. Each answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-Daily-Cap and X-Daily-Remaining. Past a limit the API answers 429 with Retry-After (seconds).
    • Rows: a key is sent up to its plan's rows a day plus the sync allowance, and its plan's rows a month (a key we set up by hand: 500,000 rows a day plus the sync allowance, and 20,000,000 rows a month) (days and months in Brisbane time; a row is one offer, product or retailer in an answer). The sync allowance is the number of offers that changed in your countries in the last 48 hours, so the daily sync (and catching up a missed day) always fits: the busiest day so far was about 350,000 changes across Australia and New Zealand, and the day after we rebuild the feed every offer counts as changed and the allowance grows to match. Each answer carries X-Rows-Daily-Cap, X-Rows-Daily-Remaining, X-Rows-Monthly-Cap and X-Rows-Monthly-Remaining. Past them: 429 row_quota_day (until midnight Brisbane) or row_quota_month (until the 1st). A page that crosses a cap is still sent whole. Drop downloads don't count against these quotas, and GET /drops still answers once you reach them: for everything at once, use the weekly drops (Growth and Pro).
    • Sweeps: more than 3,000 product lookups an hour (/products/{id}, or /offers with product= or gtin=), or more than 300 /offers pages with a cursor an hour, answers 429 sweep_throttled until the hour is up. Keep a copy with /offers/changes instead; it is not counted here.
    • Bad keys: an address that sends more than 30 requests with no key or a malformed, unknown, revoked or expired one in 10 minutes, gets 429 too_many_bad_keys for those requests until the 10 minutes are up. A request with a valid key always answers.
    • Errors are JSON: { "error": { "code": "...", "message": "..." } }, also for a path that is no endpoint (404) and a method other than GET (405).
    StatusCodeMeaning
    400unknown_parameter, repeated_parameter, bad_limit, bad_date, unknown_chain, bad_cursor...A parameter is unknown, repeated or not valid.
    401missing_key, invalid_key, expired_keyNo key, a key we don't know, or a key past its expiry.
    403revoked_key, suspended_key, country_not_in_plan, chain_not_in_plan, drops_not_in_planThe key is revoked or suspended (a plan that ended or an overdue payment), or doesn't cover what you asked for.
    404not_foundNo such product or endpoint.
    405method_not_allowedEvery endpoint is GET.
    429rate_limited, daily_cap, row_quota_day, row_quota_month, sweep_throttled, too_many_in_flight, too_many_bad_keys, download_limit_dayOver a limit. Wait Retry-After seconds.
    503unavailable, trial_data_not_readyTry again after Retry-After seconds: a minute (a trial key whose data is being prepared: an hour).

    Keys are secrets: keep them on your server, never in an app bundle. We store only a hash of each key; if you lose one, ask us for a new one and we'll revoke the old.

    Trial keys

    A trial key connects to the real API with the real schema, but its data is frozen at the end of one day (its data_until day), so you can build against it before you subscribe.

    • Every endpoint answers as of that day: offers first seen after it are not there; an offer's status, last_seen, prices and store counts are what they were that day; /offers/changes holds only changes up to the end of that day; /coverage reports up to it; /drops lists only the weekly drop's changes file cut from that day's data, and each file downloads at most 3 times (no active file and no backfill: the trial is for building against the API, not for a copy of the data). Filters, since= and cursors can't reach past it.
    • Every answer says so: JSON answers start with "trial": true, "data_until": "2026-10-28", and every response carries the headers X-Trial: true and X-Data-Until: 2026-10-28.
    • Upcoming offers are the ones announced by that day (e.g. ALDI Special Buys listed then), so their announced_start can be after it.
    • Limits: 30 requests a minute and 2,000 a day; 75,000 rows a day (no sync allowance, as the data doesn't change) and 300,000 rows a month; 300 product lookups and 30 /offers pages with a cursor an hour. Unless agreed otherwise.
    • Drop downloads: each drop file downloads at most 3 times with a trial key (CSV and Parquet together); after that it answers 403 download_limit. Downloads do not count against the row quotas.
    • Expiry: a trial key stops working at its expiry: 401 expired_key. Ask us for the paid plan and you get a live key: same calls, same fields, today's data.

    Coverage and known gaps

    GET /coverage gives the live numbers per retailer. What is known not to be there:

    • GTIN: Coles, IGA and ALDI publish no barcodes. Where the identical product at Woolworths carries one, it is supplied with gtin_source: matched (about 40% of Coles products). About 20% of New World and PAK'nSAVE products have no barcode.
    • Retailer-published offer end dates: not published on the shelf by Coles, Woolworths, ALDI or Woolworths NZ; observed dates and an inferred expected_end are supplied instead (catalogue offers carry the catalogue's dates). IGA, New World and PAK'nSAVE print end dates on many offers: announced_end.
    • The retailer's own unit price is used where the retailer prints one for the offer's price (unit_basis: measured); elsewhere it is calculated from the pack size (inferred). /coverage gives the share measured (fields_percent.unit_price_measured).
    • Member prices: sale_cents is the members' price printed on the tag, normal_cents the shelf price, where the tag gives the member price (New World Clubcard, Woolworths NZ member price).
    • Normal price at New World and PAK'nSAVE: these sites rarely show a was price, so the normal price is the last shelf price before the offer (inferred), or null when the offer began before collection did. ALDI: no normal price (normal_cents null, so no discount): ALDI shows no was price, and its specials are not compared with an earlier shelf price yet.
    • Store prices at Coles, Woolworths and ALDI: about 97% of individual store prices are filled in from a price zone or the online price; an offer's sale price is still measured when one or more of its stores was read (see stores_measured). IGA, Woolworths NZ, New World and PAK'nSAVE are read at every store.
    • Missed reads: a day a retailer was not read is listed in /coverage as days_not_read, and counts against completeness_percent (days read / days expected). On those days the previous day's values stand, so a start or end can show a day or two late. For example, Coles was not read on 21 and 22 October 2026, so those two days count against its completeness. days_built and days_not_built say which days the feed itself was built for.
    • Everyday low badges are seen from the day they appear or change; a badge that has not changed since collection began may not be listed.
    • History starts on 29 September 2026 (Australia) and 10 October 2026 (New Zealand).

    Examples

    Half-price offers at Coles in NSW:

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/offers?chain=coles&state=NSW&offer_type=half_price"

    One offer (abridged; the values are illustrative):

    {
      "id": "coles:NSW:1000051:2026-10-28",
      "status": "live",
      "source": "shelf",
      "retailer": { "id": "coles", "name": "Coles", "site": "coles.com.au" },
      "country": "AU",
      "currency": "AUD",
      "location": { "type": "state", "code": "NSW", "national": true, "scope": "all_stores", "stores_on_offer": 236, "stores_priced": 236, "stores_measured": 9 },
      "product": { "id": "coles:1000051", "retailer_code": "1000051", "gtin": "9310072000473", "gtin_source": "matched", "name": "Tim Tam Original", "brand": "Arnott's", "size": "200g" },
      "offer": { "type": "half_price", "type_basis": "inferred", "type_confidence": 0.9, "advertised": "Half price", "retailer_label": "SPECIAL", "multibuy": null },
      "prices": { "sale_cents": 300, "sale_basis": "inferred", "normal_cents": 600, "normal_basis": "measured", "unit_cents": 150, "unit_per": "100g", "unit_basis": "inferred", "discount_cents": 300, "discount_percent": 50 },
      "dates": { "first_seen": "2026-10-28", "last_seen": "2026-10-31", "dates_basis": "observed", "expected_end": "2026-11-03", "expected_end_basis": "inferred", "announced_start": null, "announced_end": null, "ended_on": null, "end_reason": null },
      "capture": { "source_site": "coles.com.au", "first_seen_at": "2026-10-28T03:12:44.000Z", "last_seen_at": "2026-10-31T03:09:10.000Z" },
      "change": { "type": "new", "day": "2026-10-28", "at": "2026-10-29T17:40:02.000Z" },
      "gaps": ["announced_end"]
    }

    Everything running on a given day in Auckland:

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/offers?country=NZ&state=NZ-AUK&active_on=2026-10-30"

    All offers for one barcode across retailers:

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/offers?gtin=9310072000473&status=all"

    Upcoming ALDI Special Buys:

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/offers?chain=aldi&status=upcoming"

    This week's drop:

    curl -s -H "X-Api-Key: $CANNONBALL_KEY" "https://app.cannonballdata.com/api/feed/v1/drops?kind=weekly"
    # then download a file's "url" (valid for 15 minutes)

    Questions: willem@cannonballdata.com.