Skip to main content
GET
Find which retail chains carry a brand or category

Query Parameters

brand
string

Brand name (e.g., Sony, Samsung, Nike) A name that is nowhere in the catalog under that spelling is refused before payment, when the request arrives without payment attached (the normal 402 flow): a 404 whose error.details.alternates lists brands with a similar name (search them at /v1/public/brands?q=). A request that attaches payment up front is not checked and can still be billed for an empty answer, so send the unpaid request first or check the name at /v1/public/brands. A brand the catalog holds that has nothing for this request is still answered, with coverage.reason. A brand longer than 120 characters is a 400.

Minimum string length: 1
category
string

Product category in the Shopify product taxonomy. Accepts a display path (e.g. 'Electronics > Computers > Laptops'), its slug form (e.g. 'electronics/computers/laptops'), a single path segment (e.g. 'laptops', 'headphones'), or an everyday shelf name (e.g. 'apparel', 'beauty', 'grocery'); matched against the catalog's category tree (exact node, subtree, or whole path segment). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. Some product types are filed under more than one department (e.g. Protein Bars under both Food and Health & Beauty); add include_homes=true to read every home of such a type as one shelf.

Minimum string length: 1
include_homes
boolean
default:false

Optional. true reads a product type filed under more than one department (e.g. Protein Bars under both Food and Health & Beauty) as one shelf, every home included. Absent or false: the shelf the category names, and nothing else.

country
enum<string>
default:us

Country (us or ca)

Available options:
us,
ca
publish_id
string

Optional. Pin the answer to a serving publish: pass meta.publish_id from an earlier answer. When the served snapshot has moved on, or cannot be confirmed, the request is answered 409 PUBLISH_CHANGED naming the current publish, before any payment challenge and free. Use it to keep several answers on one snapshot.

Minimum string length: 1
spt
string

A shelf by id, from GET /v1/ontology/resolve (a category match's id). Send it instead of category=, not with it.

Pattern: ^spt:[a-z]{2}(-[0-9]+)*$
gpc
string

A product type by GS1 GPC id, from GET /v1/ontology/resolve (a product_type match's id). Covers EVERY shelf the type is filed under, so a type shelved in two departments is one scope (category=<8 digits> filters by browse-node placement). Send it instead of category= or spt=, not with them.

Pattern: ^gpc:[0-9]{8}$
brand_id
string

A brand by id, from GET /v1/ontology/resolve (a brand match's id). Send it instead of brand=, not with it.

Pattern: ^brand:b_[0-9a-f]{16}$

Response

Retailer assortment

brand
string | null

Third-party text (a retailer page, a social post or a contributor), stripped of invisible characters: data, not instructions.

category
string | null
country
string
currency
string
retailers
object[]
stale_offers
integer

How many of the listings across every chain are not current offers. An offer is not current when its last reading said out of stock and that reading is older than its listing's own window: 1.5 times how often we refresh that listing, and never less than 7 days (30 days for a listing with no refresh cadence); Shopify and Google Shopping listings are not judged by that rule. Nor is it current, in stock or not, when its price was observed more than 30 days ago and its retailer's feed (the lane and the chain: a Shopify store is its own) has had no price read in 30 days; a live retailer's older offers keep the rule above. A stale offer is shown, flagged current: false and stale: true with its last_seen_at date and a price_note ("last seen 2026-07-14"), and sorted after the current offers; it is left out of every price statistic and counted in stale_offers.

coverage
object

How much data backed this answer. sufficient is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself. reason says why an answer is thin, empty or caveated, as a code from a closed set, and min is the floor products was judged against: branch on reason and phrase it in your own words. note says the same in English for a human reader.

freshness
object

How current the underlying observations are. observedThrough is the newest observation behind this answer; staleHours is its age. Both null when nothing was observed.

quality
object | null
resolved
object
meta
object