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 andsortthat made them, and expire: a day for/offers, 8 days for/offers/changes. Every/offers/changesanswer 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 400bad_cursor; an expired one 400cursor_expired: start the list again, or the sync withsince=(the lastchange.atyou stored). - How far back one call reaches:
/offers/changes?since=the last 8 days; on/offers,since=andactive_onthe last 31 days, and ended offers (status=endedorall, 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 400window_too_old, and so does anactive_onbefore 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'sactivefile 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/offersfor the current offers, then call/offers/changes?since=<that answer's as_of>. A trial key counts back from the end of itsdata_untilday.
Update times
All times are Brisbane time (AEST, UTC+10, no daylight saving). Sydney and Melbourne are one hour ahead from October to April.
| What | When |
|---|---|
| A day's reads | Each 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 specials | Coles, 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 drop | Cut 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 Buys | Listed 1 to 2 weeks before their on-sale date, refreshed daily. |
Endpoints
| Method and path | What it returns |
|---|---|
GET /offers | Offers, filtered, paged by cursor. Live offers unless you ask for others. |
GET /offers/changes | Offers 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 /coverage | Per 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 /drops | Weekly and backfill drops, each file a download link for your key, valid for 15 minutes. |
GET /openapi.json | The OpenAPI 3.1 description. No key needed. |
/offers filters
| Parameter | Meaning |
|---|---|
country | AU or NZ. Default: every country your key covers. |
chain | Comma-separated: coles, woolworths, iga, aldi, woolworths_nz, newworld, paknsave. |
state | Comma-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...). |
status | live (default), upcoming, ended or all. |
active_on | YYYY-MM-DD: offers running on that day (any status). Up to 31 days back, and within your plan's history (Starter: 14 days). |
offer_type | Comma-separated offer types. |
source | shelf or catalogue (see Upcoming offers). |
gtin | A barcode. |
product | A product id (coles:1000051) or a retailer code. |
since | ISO 8601 time: only offers changed after it. Up to 31 days back. |
limit | 1 to 1,000. Default 500. |
sort | quality (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. |
cursor | next_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.
| Field | Meaning | ||
|---|---|---|---|
id | Stable offer id: <retailer>:<location>:<retailer code>:<first day>. It never changes for the life of the offer. | ||
status | upcoming (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. | ||
source | shelf: read from the retailer's website. catalogue: announced ahead in the retailer's weekly catalogue. | ||
retailer.id, retailer.name, retailer.site | The retailer, and the website the offer was read from (coles.com.au...). | ||
country, currency | AU/AUD or NZ/NZD. | ||
location.type, location.code | state (AU), region (NZ) or national, and its code. | ||
location.national | True when the product is on the offer in every location where the retailer prices it that day. | ||
location.scope | Within 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_measured | Stores 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_code | The retailer's own product number. | ||
product.gtin, product.gtin_source | The 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, size | As the retailer shows them. | ||
offer.type, type_basis, type_confidence | See Offer types. | ||
offer.advertised | The deal in words: Half price, 40% off, Save $1.50, 2 for $5.00, Member price. | ||
offer.retailer_label | The retailer's own offer code, unchanged (`SPECIAL | MULTI_SAVE, TPR | 40%_OFF`). |
offer.multibuy | For multibuys: quantity, price_cents (for the quantity) and price_each_cents. | ||
prices.sale_cents | The 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_basis | The "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_basis | Sale 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_percent | Normal minus sale, and as a percentage of normal. Null without a normal price. | ||
dates.first_seen, last_seen | The first and last day the offer was seen on the retailer's website (dates_basis: observed). | ||
dates.expected_end, expected_end_basis | When 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_end | Start and end dates the retailer published, where it did. | ||
dates.ended_on, end_reason | The 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_zone | The 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_at | The site read, and when the price was first and last read (UTC). | ||
change.type, day, at | The 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). | ||
gaps | The fields this offer lacks, for example ["gtin", "announced_end"]. | ||
ref | Your 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.
| Order | offer.type | Rule | type_basis |
|---|---|---|---|
| 1 | multibuy | The 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 |
| 2 | member_price | A loyalty members' price: New World Clubcard, Woolworths NZ member price. | measured |
| 3 | clearance | Marked clearance or "while stocks last". | measured |
| 4 | half_price | The 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) |
| 5 | better_than_half_price | The retailer's label says better than half price (IGA, Woolworths NZ). Kept apart so you can merge it with half price or not. | measured |
| 6 | discount | Any other price reduction: a special, a percentage off, "save $X". offer.advertised says which. | measured |
| 7 | everyday_low | An 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 |
| 8 | special_buy | An ALDI Special Buy, announced ahead with its on-sale date. | measured |
| 9 | promotion_label_missing | The 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. Forsale_cents: read at one or more of the location's stores;location.stores_measuredsays 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. Fornormal_cents: the retailer's own was price.announced(sale_centsonly): the price in the retailer's catalogue or ALDI's Special Buys list, read at no store (stores_measured0): 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 andmeasured).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.
/offersand/offers/changesanswer with anETag. Send it back asIf-None-Match: when nothing was published since (and no offer's status moved at a local midnight), the answer is304 Not Modifiedwith no body and counts no rows. It still counts as a request against the per-minute limit. - Cursor or time.
next_cursorcontinues exactly after the last change you received. Or pass the last answer'sas_ofas the nextsince:as_ofis the time of the latest publish, and every change published after it has a laterchange.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 aschanged(or asendedwithend_reason: withdrawnif 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/coverageentry):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) andpublished_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_labelis the catalogue's own wording ("1/2 Price, Save $11.50"). Items in the catalogue with no offer wording are left out. They reach/offersand/offers/changeswith the nightly update after we read the catalogue (usually by Wednesday 07:00 Brisbane), asupcominguntil midnight on the start date in each state's time zone (dates.starts_at), thenlive.
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) andchanges(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-CapandX-Daily-Remaining. Past a limit the API answers 429 withRetry-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-CapandX-Rows-Monthly-Remaining. Past them: 429row_quota_day(until midnight Brisbane) orrow_quota_month(until the 1st). A page that crosses a cap is still sent whole. Drop downloads don't count against these quotas, andGET /dropsstill 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/offerswithproduct=orgtin=), or more than 300/offerspages with acursoran hour, answers 429sweep_throttleduntil the hour is up. Keep a copy with/offers/changesinstead; 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_keysfor 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).
| Status | Code | Meaning |
|---|---|---|
| 400 | unknown_parameter, repeated_parameter, bad_limit, bad_date, unknown_chain, bad_cursor... | A parameter is unknown, repeated or not valid. |
| 401 | missing_key, invalid_key, expired_key | No key, a key we don't know, or a key past its expiry. |
| 403 | revoked_key, suspended_key, country_not_in_plan, chain_not_in_plan, drops_not_in_plan | The key is revoked or suspended (a plan that ended or an overdue payment), or doesn't cover what you asked for. |
| 404 | not_found | No such product or endpoint. |
| 405 | method_not_allowed | Every endpoint is GET. |
| 429 | rate_limited, daily_cap, row_quota_day, row_quota_month, sweep_throttled, too_many_in_flight, too_many_bad_keys, download_limit_day | Over a limit. Wait Retry-After seconds. |
| 503 | unavailable, trial_data_not_ready | Try 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/changesholds only changes up to the end of that day;/coveragereports up to it;/dropslists only the weekly drop'schangesfile cut from that day's data, and each file downloads at most 3 times (noactivefile 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 headersX-Trial: trueandX-Data-Until: 2026-10-28. - Upcoming offers are the ones announced by that day (e.g. ALDI Special Buys listed then), so their
announced_startcan 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
/offerspages 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_endare 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)./coveragegives the share measured (fields_percent.unit_price_measured). - Member prices:
sale_centsis the members' price printed on the tag,normal_centsthe 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_centsnull, 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
measuredwhen one or more of its stores was read (seestores_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
/coverageasdays_not_read, and counts againstcompleteness_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_builtanddays_not_builtsay 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.