Skip to content
  • There are no suggestions because the search field is empty.

Analytics API Guide

In order to use the Analytics API, you will first need to create an API Key.

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 <api-key>

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

 

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.

 

 

For our full API Guide, please click here.