Sardius MediaSupport

Analytics API Guide

Updated

Overview

This guide explains how to call Sardius analytics endpoints to build:

  • Unique / Total viewers
  • USA: Top 5 states
  • Global: Top 5 countries (excluding the US)

Prerequisites

Sardius will provide:

  • accountId
  • Bearer API key

Send this header on every request:

Authorization: Bearer

Base URL

https://api.sardius.media/analytics/{accountId}

Endpoint recipes

1) Unique / Total Viewers

Request

GET /analytics/{accountId}/youbora?fromDate=last5minutes&metrics=views,uniques&operation=reducejoin

What this returns

  • One aggregate total for views
  • One aggregate total for uniques

How to parse

  1. Read const metrics = response.data[0].metrics.
  2. Find metric blocks:
    • viewsMetric = metrics.find(m => m.code === "views")
    • uniquesMetric = metrics.find(m => m.code === "uniques")
  3. Extract values safely:
    • views = viewsMetric?.values?.[0]?.data?.[0]?.value ?? 0
    • uniques = uniquesMetric?.values?.[0]?.data?.[0]?.value ?? 0

Sample interpretation

  • views = 206 (total plays in window)
  • uniques = 23 (unique users in window)

2) USA Top 5 States

Request

GET /analytics/{accountId}/youbora/list/state_province?fromDate=last5minutes&metrics=views,uniques&country=United%20States&limit=5

What this returns

  • Ranked rows by state_province for each metric (views, uniques)

How to parse

  1. Read const metrics = response.data[0].metrics.
  2. Find metric blocks:
    • viewsMetric = metrics.find(m => m.code === "views")
    • uniquesMetric = metrics.find(m => m.code === "uniques")
  3. Convert both arrays to maps keyed by state_province.
  4. Build combined rows:
    • { label: state_province, views, uniques }
  5. Drop invalid rows:
    • blank label
    • views === 0 && uniques === 0
  6. Keep first 5 rows.

Sample interpretation

  • Kansas = views 115, uniques 7
  • Missouri = views 8, uniques 3
  • Texas = views 1, uniques 1
  • Virginia = views 1, uniques 1

3) Global Top 5 Countries (excluding US)

Request

GET /analytics/{accountId}/youbora/list/country?fromDate=last5minutes&metrics=views,uniques&limit=10

Why limit=10

If United States is in the results and must be excluded, you still want enough rows left to display 5 non‑US countries.

How to parse

  1. Parse rows into { label: country, views, uniques }.
  2. Remove rows where label === "United States".
  3. Sort remaining rows by views descending (if needed).
  4. Keep first 5 non‑US rows.

Sample interpretation (before exclusion)

  • United States = views 125, uniques 12
  • Paraguay = views 55, uniques 6
  • Argentina = views 18, uniques 3
  • United Kingdom = views 7, uniques 1
  • Egypt = views 1, uniques 1

If US is excluded, output starts with:

  • Paraguay, Argentina, United Kingdom, Egypt, ...

Shared response rules

  • data[0].dimensions confirms applied filters (for example country = United States).
  • data[0].metrics contains one block per requested metric code.
  • offset is an NPAW response field, not a pagination cursor you should reuse.
  • Join views and uniques by label (country / state_province), not by array index.
  • If fewer than 5 valid rows are returned, display available rows only.

Choosing a time window (fromDate)

Use these defaults unless you need a different reporting window:

  • Live / “callout board”: last5minutes
  • Less noisy near‑live: lasthour or last3hours
  • Historical context: last30Days

If omitted, Sardius defaults to last6hours.

cURL examples

Replace placeholders before running.

curl --request GET \
  --url "https://api.sardius.media/analytics/{accountId}/youbora?fromDate=last5minutes&metrics=views,uniques&operation=reducejoin" \
  --header "Authorization: Bearer "

curl --request GET \
  --url "https://api.sardius.media/analytics/{accountId}/youbora/list/state\_province?fromDate=last5minutes&metrics=views,uniques&country=United%20States&limit=5" \
  --header "Authorization: Bearer "

curl --request GET \
  --url "https://api.sardius.media/analytics/{accountId}/youbora/list/country?fromDate=last5minutes&metrics=views,uniques&limit=10" \
  --header "Authorization: Bearer "

Troubleshooting

  • 401/403: Check API key and account access scope.
  • Empty US states:
    • Confirm country=United%20States.
    • Filter out blank state_province.
  • No data in short windows:
    • Increase window (lasthour, last3hours, or last24hours).
  • Global excluding US:
    • Remove "United States" client-side before selecting top 5 non‑US rows.

Related articles