Skip to main content
GET
Rank brands by share-of-conversation vs share-of-shelf gap

Query Parameters

category
string

Shopify taxonomy path, as a join key or a display path: a root (food-beverages-tobacco) or any node under it. A brand is filed at one node and counted there and at every ancestor, so each depth is its own scope. A node no tracked brand sits under is refused free, with the published scopes that contain it. Retired browse roots (grocery-gourmet-food, ...) are refused with the root to use instead. The shelf side reads the same node, so both shares divide up one category. No wildcard: these answers are ranked comparisons.

country
enum<string>
default:us

Country for the SHELF side of the join.

Available options:
us,
ca
window
enum<string>
default:30d

Rollup window. Only published windows are accepted.

Available options:
30d,
90d
platform
enum<string>
default:all

TikTok and Instagram are the only platforms in the corpus.

Available options:
all,
tiktok,
instagram
organic_only
boolean
default:false

Exclude posts marked as ads.

limit
integer
default:25

Maximum ranked brands to return.

Required range: 1 <= x <= 100
spt
string

A shelf by id, from GET /v1/ontology/resolve (a category match's id). Send it instead of category=, not with it. The answer is about that one node, as with category=.

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

Response

Attention vs shelf ranking

category
string
country
string
currency
string
window_days
integer
platform
string
organic_only
boolean
brands
object[]
corpus_mentions
integer

The conversation the shares divide up. A share of 40 mentions is not the same kind of fact as a share of 40,000.

thin_corpus
string

Present when the whole category's corpus is below the depth floor: the ranking is arithmetic, not a market signal.

unmatched
object

Rows dropped per side because their brand key has no counterpart. Counted, never fuzzy-matched.

coverage
object

TWO blocks — social counts mention subjects, shelf counts products. Never merged.

freshness
object

TWO values — weekly social, daily serving. Never the max.

snapshot
object | null
resolved
object
meta
object