Skip to main content
GET
What sits next to an id

Query Parameters

id
string
required

An id from resolve: spt:…, gpc:…, brand:… or retailer:….

Pattern: ^(spt|gpc|brand|retailer):.+$
relations
string

Comma-joined or repeated: which blocks to return. category: ancestors, children, siblings, types, parallel_homes, aliases, top_brands, top_retailers, facets, labels (only when named). product_type: ancestry, homes, siblings, aliases. brand: profile, aliases, footprint, carried_at, not_observed_at, similar. retailer: profile, assortment, brands. A brand's similar is { status, basis, items, total, truncated, n_entities, best_score, weak, reason }: up to 10 brands that share its shelves (four levels deep) at a similar price tier, best first, each with rank, score, overlap, price_gap and the shared shelves behind it; status: unavailable means the table is not published yet, which is not the same as no list. n_entities is the brand's distinct products on shelves (the number the floor of 5 tests), best_score the best match's score, and weak the one rule for a list that cannot be leaned on: the best score is under 0.3 or fewer than 3 brands cleared (an empty list is weak). When items is empty, reason says why: homonym (one id for two companies: no peers by design), not_a_brand (a storefront phrase in the brand field), no_footprint (no product on a shelf), below_floor (under 5 distinct products on shelves) or no_overlap (enough products, no brand shares 0.2 of its shelves). The four fields are null until the status table is published. It never uses a brand's own description, and shelves alone cannot tell two brands apart that sell the same things at the same price. An unknown one is a 400 that lists the valid ones for the kind.

limit
integer
default:25

Most items in each list. Over the maximum is a 400, not a silent clamp, so a capped list is never mistaken for the whole one.

Required range: 1 <= x <= 200
country
enum<string>
default:us

Coverage is per country, so a typo is a 400 rather than a quiet read of the other one.

Available options:
us,
ca

Response

The answer, naming the vocabulary release it came from

id
string
required
kind
enum<string>
required
Available options:
category,
product_type,
brand,
retailer
label
string
required
country
enum<string>
required
Available options:
us,
ca
relations
object
required

The blocks asked for with relations= (the kind's defaults when absent), by name. A list is { items, total, truncated }: total is how many there are before the limit= cap. A category's facets block is the marketing practices creators say brands do on the shelf (30 days, all platforms): { status, basis: creator_stated, window_days, items, total, truncated }, each item a practice (id, channel, lane, practice, label) with creators, posts, brands, example_brands, cadence_per_month_median, cadence_n and last_seen. status: unavailable means the social data is not published on this deployment, which is not the same as no practice. A category's labels block (only when asked for with relations=labels, never in the default answer) is what the posts about the shelf are: { status, window_days, kinds, themes, facets, total, truncated }, each list holding items { type, id, label, creators, posts, brands, example_brands, last_seen }, where kinds are what a post does (advice, story, pitch, showcase, demo, news, insight, review), themes what it is about and facets who it is for or what stage it is at; status: unavailable means the labels are not published on this deployment, which is not the same as none.

vocab
object
required

The vocabulary release that answered, so an answer can be tied to the taxonomy, product-type map and aliases it was built from. The first three are also the X-Taxonomy-Release, X-GPC-Release and X-Map-Version response headers.

schema_version
string
required
Example:

"ontology/1"

coverage
object | null

The denominators behind an answer, for the country asked. retailers_scanned is the chains looked at where this lives: "not seen at X" may be said only when X is in it, and a chain outside it is unknown, not absent. channels_not_observed are the known channels with no evidence at all, the only reason "no in-store price" can be said.

suggested_next_calls
object[]

The calls that make sense next, with the ids filled in and the price beside each. A convenience, not an instruction: everything stays available. Never a result, and empty when a name is ambiguous (the choice is yours) or missed.