Skip to main content
GET
Names to ids, across shelves, product types, brands and chains

Query Parameters

term
string[]
required

A name to resolve: a category, a product type, a brand, a chain, a hashtag. Repeat the parameter for a batch (term=soda&term=olipop), one concept per term and at most 25: terms=a,b is refused, because a comma can sit inside a real name. A marketing practice ('founder letter', 'restock email') resolves to a facet match, and a word creators tag their posts with ('fiber', 'prebiotic soda') to a topic match. Ownership facets such as woman-owned are not served yet: they come back as a miss.

Required string length: 1 - 200
kinds
string

Comma-joined or repeated: which kinds a term may resolve to. Default category,product_type,brand,retailer,facet,topic. Add entity to look up one physical product by name (a brand plus its words); it costs more, so it is asked for.

within
string

An spt or gpc id naming the shelf the question is on. Hits standing in it stay in matches, the rest move to also_ok, and each carries where it stands. It never invents a primary: with no footprint in the scope nothing is promoted (within_applied: false).

Pattern: (^spt:[a-z]{2}(-[0-9]+)*$)|(^gpc:[0-9]{8}$)
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

results
object[]
required

One per term=, in the order sent.

country
enum<string>
required
Available options:
us,
ca
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"

suggested_next_calls
object[]

Calls that need two terms to name: a brand from one term on a shelf from another.

topics
object

Only when topic is among the kinds asked for (it is by default) and a term could be a tag (3 to 30 letters and digits once its words are joined): whether the latest social rollup's topics were read. unavailable means the social data is not published on this deployment or could not be read, so a term with no topic match is not a finding that nobody tags it.

within
object

Only when within= was sent: the scope it named.