Guide: build a category league table
Goal: rank every brand in a category on a metric.
Two approaches
| Rankings endpoint | Analysis "all brands" expansion | |
|---|---|---|
| Output | Ordered table with rank, score, movement | One time series per brand |
| Best for | A ready-made league table / scorecard | Charting each brand's trend |
| Ordering | Done for you | You sort client-side |
Option A — the rankings endpoint (recommended for a table)
{
"meta": { "version": "v1" },
"data": {
"entities": [
{ "brands_from_sector_id": 1, "region": "us", "only_active": true }
],
"period": { "start_date": { "days": 30 }, "end_date": { "days": 1 } },
"comparison_period": { "start_date": { "days": 60 }, "end_date": { "days": 31 } },
"scoring": "total",
"metrics_score_types": { "buzz": "net_score" },
"filters": [],
"significance_percentages": [95]
}
}
POST to /v1/rankings/execute. You get ranked rows with positions and
movement versus the comparison period.
Option B — an analysis "all brands" expansion
{
"meta": { "version": "v1" },
"data": {
"queries": [
{
"id": "sector-ranking",
"entity": { "brands_from_sector_id": 1, "region": "us", "only_active": true },
"period": { "start_date": { "days": 30 }, "end_date": { "days": 1 } },
"metrics_score_types": { "aided": "net_score" },
"filters": []
}
]
}
}
POST to /v1/analyses/execute. The single query expands into one series per
brand; sort them yourself by the metric.
Watch the data limits
Expanding a large sector multiplies the brand count and therefore the request
size. If you hit a 400, narrow the period, reduce metrics, or split the work.
See Request size & limits.