City operational report - plays and screens, load, anomalies

GET /api/v1/stats/reports

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

Анықтамалықтың техникалық мәтіні ағылшын тілінде жазылған.

Scope read:stats. Own organisation; the authority sees the city. Answered from the hourly aggregates; days are Asia/Almaty days. series holds plays and active screens (structures with a play) per period, district and format; load the distribution of plays per screen per day; anomalies the screens to look at; reconciliation the plays an operator imported against the plays the players reported, per structure, approval and finished day.

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

Authorization тақырыбындағы API кілті немесе консоль сеансы.

Рұқсат: read:stats

Параметрлер

Атауы	Орны	Түрі	Міндетті	Сипаттама	Мысал
`from`	сұрау	string (date)	жоқ	First day (default 29 days back).	`2026-09-08`
`to`	сұрау	string (date)	жоқ	Last day (default today).	`2026-10-06`
`grain`	сұрау	string	жоқ	Length of one period: `day`, `week` or `month`. day, week, month	`day`

Жауаптар

200 The report sections.

`application/json`

Атауы	Түрі	Міндетті	Сипаттама	Мысал
`from`	string (date)	иә	First day of the report.	`"2026-09-08"`
`to`	string (date)	иә	Last day of the report.	`"2026-10-06"`
`grain`	string	иә	Length of one period in `series`: day, week or month.	`"day"`
`series`	array of object	иә	Plays and active screens for each period, district and format.
`series[].period`	string (date)	иә	First day of the period.	`"2026-10-05"`
`series[].district`	string	иә	Code of the district.	`"bostandyk"`
`series[].format`	string	иә	Code of the format.	`"cityboard"`
`series[].plays`	integer	иә	Plays in the period.	`48210`
`series[].screens`	integer	иә	Screens with at least one play in the period.	`36`
`load`	object	иә	How plays per screen per day are distributed.
`load.screen_days`	integer	иә	Number of screen-days counted.	`1008`
`load.mean`	integer	иә	Mean plays per screen per day.	`1340`
`load.median`	integer	иә	Median plays per screen per day.	`1325`
`load.p10`	integer	иә	Plays per screen per day that 10 % of screen-days stay under.	`980`
`load.p90`	integer	иә	Plays per screen per day that 90 % of screen-days stay under.	`1710`
`load.max`	integer	иә	Most plays on one screen in one day.	`2010`
`load.histogram`	array of object	иә	Screen-days by bands of plays.
`load.histogram[].from`	integer	иә	Lower edge of the band, in plays.	`1000`
`load.histogram[].to`	integer	иә	Upper edge of the band, in plays.	`1500`
`load.histogram[].count`	integer	иә	Screen-days in the band.	`412`
`anomalies`	array of object	иә	The screens to look at.
`anomalies[].kind`	string	иә	What was found. low_plays, silent, refusal_spike
`anomalies[].structure_id`	string (uuid)	иә	Identifier of the structure.	`"b7e4a2c9-0d1f-4a68-8e35-91c7f2d40b16"`
`anomalies[].code`	string	иә	Code of the structure.	`"ALM-0012"`
`anomalies[].address`	string	иә	Street address of the structure.	`"Al-Farabi Ave 77/7"`
`anomalies[].district`	string	иә	Code of the district.	`"bostandyk"`
`anomalies[].observed`	integer	иә	Plays observed on that day.	`120`
`anomalies[].baseline`	integer	иә	Plays expected from the structure's own history.	`1300`
`anomalies[].day`	string	иә	The Asia/Almaty day concerned.	`"2026-10-05"`
`reconciliation`	array of object	иә	Imported plays against reported plays, for each structure, approval and finished day.
`reconciliation[].day`	string (date)	иә	The Asia/Almaty day compared.	`"2026-10-05"`
`reconciliation[].structure`	string	иә	Structure code.	`"ALM-0012"`
`reconciliation[].approval_number`	string	иә	Number of the approval compared.	`"TNB-2026-000123"`
`reconciliation[].imported_plays`	integer	иә	Plays the operator imported for that day.	`2830`
`reconciliation[].reported_plays`	integer	иә	Plays the players reported for that day.	`2841`
`reconciliation[].reconciled_ratio`	number \| null	иә	Imported divided by reported; null while the players reported nothing.	`0.996`

Мысал

{
  "from": "2026-09-08",
  "to": "2026-10-06",
  "grain": "day",
  "series": [
    {
      "period": "2026-10-05",
      "district": "bostandyk",
      "format": "cityboard",
      "plays": 48210,
      "screens": 36
    }
  ],
  "load": {
    "screen_days": 1008,
    "mean": 1340,
    "median": 1325,
    "p10": 980,
    "p90": 1710,
    "max": 2010,
    "histogram": [
      {
        "from": 1000,
        "to": 1500,
        "count": 412
      }
    ]
  },
  "anomalies": [
    {
      "kind": "low_plays",
      "structure_id": "b7e4a2c9-0d1f-4a68-8e35-91c7f2d40b16",
      "code": "ALM-0012",
      "address": "Al-Farabi Ave 77/7",
      "district": "bostandyk",
      "observed": 120,
      "baseline": 1300,
      "day": "2026-10-05"
    }
  ],
  "reconciliation": [
    {
      "day": "2026-10-05",
      "structure": "ALM-0012",
      "approval_number": "TNB-2026-000123",
      "imported_plays": 2830,
      "reported_plays": 2841,
      "reconciled_ratio": 0.996
    }
  ]
}

Қателер

Қателер problem құжаты (application/problem+json) түрінде, тұрақты code өрісімен келеді.

Мәртебесі	Мағынасы
401	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
422	Field errors (`validation_failed`).
default	An error as a problem document.

Код мысалдары

curl

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

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/stats/reports",
    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/reports", 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))
}