List structures

GET /api/v1/structures

https://app.tanba-ooh.kz/api/v1/structures

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

Scope read:structures. Filters district, format, class, status, org_id (authority only), paging by limit (1-500) and offset.

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

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

Рұқсат: read:structures

Параметрлер

Атауы	Орны	Түрі	Міндетті	Сипаттама	Мысал
`limit`	сұрау	integer	жоқ	How many structures to return, 1 to 500.	`100`
`offset`	сұрау	integer	жоқ	How many structures to skip.	`0`

Жауаптар

200 Structures ordered by code.

`application/json`

Атауы	Түрі	Міндетті	Сипаттама	Мысал
`items`	array of Structure	иә	Structures ordered by code.
`items[].id`	string (uuid)	иә	Identifier of the structure.	`"b7e4a2c9-0d1f-4a68-8e35-91c7f2d40b16"`
`items[].org_id`	string (uuid)	иә	Identifier of the operating organisation.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`items[].org_name`	string		Name of the operating organisation.	`"Alma Outdoor LLP"`
`items[].code`	string	иә	Structure code printed on the sticker.	`"ALM-0012"`
`items[].unos_id`	string \| null		Identifier of the structure in the external register; null if it has none.	`"A-004711"`
`items[].address`	string	иә	Street address.	`"Al-Farabi Ave 77/7"`
`items[].district_id`	string	иә	Code of the district.	`"bostandyk"`
`items[].format_id`	string	иә	Code of the format.	`"cityboard"`
`items[].lat`	number	иә	Latitude in degrees.	`43.2186`
`items[].lng`	number	иә	Longitude in degrees.	`76.9279`
`items[].class`	string	иә	Class of the structure. A, B, C
`items[].status`	string	иә	Whether the structure is in use. active, decommissioned
`items[].screen_width_px`	integer \| null		Native screen width. Set together with the height; the media check compares uploads with it.	`1920`
`items[].screen_height_px`	integer \| null		Native screen height.	`1080`
`items[].slot_seconds`	integer \| null		Longest video the structure plays in one slot. Longer videos fail the slot check.	`10`
`items[].venue_type_id`	integer \| null		Venue type of the structure in the OpenOOH venue taxonomy 1.2 (for example 302 for an urban panel). Null while the operator has not set one; market figures then use the default venue type of the format.	`302`
`items[].loop_seconds`	integer \| null		Length in seconds of one full loop of the screen, as set by the operator. Null while unknown.	`60`
`items[].face_area_m2`	number \| null		Area of the advertising face in square metres. Null while unknown.	`22.5`
`items[].screen_count`	integer		Number of screens on the structure.	`2`
`items[].height_m`	number \| null		Height of the face above the ground in metres. Null while unknown.	`6.5`
`items[].azimuth_deg`	integer \| null		Compass direction the face looks to, in degrees from north. Null while unknown.	`270`
`items[].operating_from`	string \| null		Time the screen starts each day (Asia/Almaty). Null while unknown.	`"06:00"`
`items[].operating_to`	string \| null		Time the screen stops; it may be earlier than the start when the hours cross midnight.	`"01:00"`
`items[].created_at`	string	иә	When the structure was registered.	`"2026-03-12T10:15:00+05:00"`
`items[].updated_at`	string		When the structure was last changed.	`"2026-09-30T16:40:12+05:00"`

Мысал

{
  "items": [
    {
      "id": "b7e4a2c9-0d1f-4a68-8e35-91c7f2d40b16",
      "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
      "org_name": "Alma Outdoor LLP",
      "code": "ALM-0012",
      "unos_id": "A-004711",
      "address": "Al-Farabi Ave 77/7",
      "district_id": "bostandyk",
      "format_id": "cityboard",
      "lat": 43.2186,
      "lng": 76.9279,
      "class": "A",
      "status": "active",
      "screen_width_px": 1920,
      "screen_height_px": 1080,
      "slot_seconds": 10,
      "venue_type_id": 302,
      "loop_seconds": 60,
      "face_area_m2": 22.5,
      "screen_count": 2,
      "height_m": 6.5,
      "azimuth_deg": 270,
      "operating_from": "06:00",
      "operating_to": "01:00",
      "created_at": "2026-03-12T10:15:00+05:00",
      "updated_at": "2026-09-30T16:40:12+05:00"
    }
  ]
}

Қателер

Қателер 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/structures' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

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