Skip to main content

Execute a ranking

Maps to: POST /v1/rankings/execute

Runs a ranking from a definition and returns the ordered result. This page covers what is specific to rankings; for the shared building blocks (entities, periods, metrics, filters) see Concepts.

Request​

POST /v1/rankings/execute
{
  "meta": { "version": "v1" },
  "data": {
    "id": "sector-buzz-ranking",
    "title": "Buzz ranking",
    "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, 90]
  }
}

Key fields:

FieldRequiredNotes
entitiesYesA list of entities to rank. Usually a single "all brands" expansion, but can be an explicit list of brands.
periodYesThe window to score and rank over.
metrics_score_typesYesThe metric(s) to rank on and how to score them.
scoringYesThe base population.
filtersYesAudience filters (may be []).
comparison_periodNoA second window; enables position change vs. the main period.
significance_percentagesNoConfidence levels for which the result includes significance thresholds (e.g. [95, 90]) — see Response.

Unlike an analysis, these apply to the ranking as a whole — there are no per-query settings, and there is no moving average or resampling (a ranking is a snapshot, not a series).

Response​

data is an object keyed by metric name — one key per entry in metrics_score_types — whose value is the ordered list of ranked entities for that metric:

"data": {
  "buzz": [
    {
      "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
      "position": { "rank": 1, "score": 31.5, "volume": 502.0 },
      "comparison_position": { "rank": 2, "score": 28.9, "volume": 489.0 },
      "position_change": { "rank": 1, "score": 2.6, "volume": 13.0 },
      "trend": 1,
      "days_with_score": 30,
      "last_day_with_data": "2024-06-30",
      "rank_significance_diffs": [
        { "percentage": 95, "up": 3.1, "down": -3.4 },
        { "percentage": 90, "up": 2.6, "down": -2.8 }
      ]
    }
  ]
}

Each ranked entity carries:

  • entity — the ranked entity: usually a brand, but a ranking can also rank sectors, custom sectors or industries.
  • position — its rank, score and volume in the main period.
  • comparison_position — the same for the comparison period, and position_change — the difference between the two (both null when no comparison_period was supplied).
  • trend — an integer trend indicator; days_with_score and last_day_with_data — how much of the period the entity actually has data for.
  • rank_significance_diffs — one entry per requested confidence percentage (see below), or null when significance_percentages was not supplied.

Significance thresholds, not flags​

significance_percentages does not flag movements in the response. For each requested confidence level, each entity gets numeric up and down score-change thresholds relative to its comparison-period score. Compare the entity's actual score change (position_change.score) against them: a change greater than up, or less than down, is significant at that confidence level.

CSV output​

Append .csv for a flat file:

POST /v1/rankings/execute.csv