Plays grouped by a dimension, by day or by hour

GET /api/v1/stats/plays

https://app.tanba-ooh.kz/api/v1/stats/plays

Технический текст справочника написан на английском.

Scope read:stats. Own organisation; the authority and analysts see the city. The plays are the ones the bill counts: per structure, approval and hour the billable tier with the most plays gives the figure and tiers are never added up, so the total of any dimension equals the total by structure. by picks the dimension: structure, approval, district, format, class, daypart (the Almaty dayparts of the dictionary) or category (the product category of the submission behind the approval; none when it has none). grain cuts each key into Almaty days (up to 90) or hours (up to 7 days). Keys come busiest first and are paged with limit and offset; total is the number of keys and plays_total the plays of all of them. tiers splits the plays of a key by the tier that gave their basis, so the four numbers add up to total. With output=csv every key is returned, one row per key and bucket that has plays.

Аутентификация

Ключ API в заголовке Authorization или сессия консоли.

Право доступа: read:stats

Параметры

Имя	Где	Тип	Обязательный	Описание	Пример
`by`	запрос	string	нет	Dimension to group by. structure, approval, district, format, class, daypart, category	`district`
`grain`	запрос	string	нет	Length of one bucket: an Almaty `day` or an `hour`. day, hour	`day`
`days`	запрос	integer	нет	Days back, today included. Up to 90 with `grain=day`; up to 7 (default 1) with `grain=hour`.	`30`
`limit`	запрос	integer	нет	Keys per page; ignored with `output=csv`.	`50`
`offset`	запрос	integer	нет	Keys to skip; ignored with `output=csv`.	`0`
`output`	запрос	string	нет	`csv` returns UTF-8 with a byte-order mark and the columns key, label, bucket, plays, plays_mtls, plays_signed, plays_attested, plays_native. json, csv	`json`
`sep`	запрос	string	нет	Column separator; `semicolon` for spreadsheets set to a comma decimal mark. comma, semicolon	`comma`

Ответы

200 The keys with their plays per bucket, or a CSV with `output=csv`.

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`by`	string	да	The dimension asked for.	`"district"`
`grain`	string	да	Length of one bucket. day, hour
`days`	array of string (date)		With `grain=day`, the first moment of each bucket as an Almaty date; `counts` of an item follow this order.
`hours`	array of string (date-time)		With `grain=hour`, the start of each bucket as an Almaty timestamp; `counts` of an item follow this order.
`items`	array of PlayStat	да	One entry per key on this page, busiest first.
`items[].key`	string	да	Stable value of the dimension: a structure id, an approval number, a district, format, class or daypart code, a category id or `none`.	`"medeu"`
`items[].label`	string	да	Readable name of the key in English (the structure code for `structure`).	`"Medeu"`
`items[].total`	integer (int64)	да	Plays of the key in the whole window.	`18420`
`items[].counts`	array of integer (int64)	да	Plays per bucket, in the order of `days` or `hours`.
`items[].tiers`	object	да	Plays of the key by the tier that gave their basis; the four numbers add up to `total`.
`items[].tiers.mtls`	integer (int64)	да	Plays on the device-certificate tier.	`18420`
`items[].tiers.signed`	integer (int64)	да	Plays on the device-signature tier.	`0`
`items[].tiers.attested`	integer (int64)	да	Plays on the signed operator CMS tier.	`0`
`items[].tiers.native`	integer (int64)	да	Plays on the player-report tier.	`0`
`total`	integer	да	Number of keys, across all pages.	`12`
`plays_total`	integer (int64)	да	Plays of all keys, across all pages.	`481200`

Пример

{
  "by": "district",
  "grain": "day",
  "days": [
    "2026-10-12"
  ],
  "hours": [
    "2026-10-12T14:00:00+05:00"
  ],
  "items": [
    {
      "key": "medeu",
      "label": "Medeu",
      "total": 18420,
      "counts": [
        612
      ],
      "tiers": {
        "mtls": 18420,
        "signed": 0,
        "attested": 0,
        "native": 0
      }
    }
  ],
  "total": 12,
  "plays_total": 481200
}

`text/csv`

Пример

string

Ошибки

Ошибки приходят документом problem (application/problem+json) со стабильным полем code.

Статус	Значение
401	Нет действительной сессии или ключа API (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	Роль или право ключа этого не допускает (`forbidden`, `key_scope_denied`, `key_route_denied`).
422	Ошибки полей (`validation_failed`).
default	Ошибка в виде документа problem.

Примеры кода

curl

curl 'https://app.tanba-ooh.kz/api/v1/stats/plays' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/stats/plays",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://app.tanba-ooh.kz/api/v1/stats/plays", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}