Skip to main content
GET
A name, phrase or code to ids.

Query Parameters

subject
string

What the question is about: an id (spt:, gpc:, brand:, retailer:, entity:) or a name. It is sent to the answering route as the parameter of its kind (an spt: id as spt, a brand: id as brand_id, a name as the route's name parameter), so send it OR that parameter, not both. Which kinds a split takes is in x-syntalic-presets; a kind it does not take is refused before anything is billed.

by
enum<string>
default:name

How the answer is split. Each value is answered by one existing route; see x-syntalic-presets.

Available options:
name,
browse_node,
gpc_browse_nodes,
gpc_attributes
term
string[]

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
browse_id
string

Comma-separated Amazon browse node ids (max 100 per request). Provide either browse_id or q, not both.

Pattern: ^\d{1,20}(,\d{1,20})*$
q
string

Comma-separated product-type phrases to resolve to GPC bricks or classes via the curated lexicon, e.g. 'protein bars' or 'coffee'. Max 100 per request. Only an ASCII comma separates phrases. Certain-or-blank: a phrase the lexicon does not carry returns an empty gpc list plus miss { reason, detail, hint, try, candidates }, never a nearest guess. A class hit includes forms[]. Provide either browse_id or q, not both.

gpc_code
string

Comma-separated 8-digit GS1 GPC codes (max 100 per request)

Pattern: ^\d{8}(,\d{8})*$

Response

The answer of the route that by selected, unchanged. The X-Syntalic-Preset response header names that route; its own path in this document has the response schema.

The response is of type object.