---
swagger: '2.0'
info:
  version: '1.0'
  title: SaveEcoBot API моніторингу якості повітря
  description: SaveEcoBot – єдина в Україні екологічна система, яка поєднує дані про забруднення, забруднювачів та інструменти захисту довкілля.<br/>Це API надає дані моніторингу якості атмосферного повітря, які збираються й нормалізуються SaveEcoBot.<br/>Для отримання ключа доступу заповніть <a href="https://forms.gle/KfPsHd1shXYGfYHW6" target="_blank">анкету за посиланням</a>.
  contact:
    name: SaveDnipro
    email: savednipro@gmail.com
  termsOfService: https://www.saveecobot.com/static/terms
host: www.saveecobot.com
basePath: "/api/v1"
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  apikey:
    type: apiKey
    name: apikey
    in: query
paths:
  "/cities":
    get:
      tags:
      - Населені пункти
      summary: Пошук населених пунктів
      description: Отримання переліку населених пунктів, у яких встановлені станцій моніторингу з можливістю фільтрації по регіону.
      responses:
        '200':
          description: OK
          examples:
            application/json:
              meta:
                page:
                  current-page: 1
                  per-page: 1
                  from: 1
                  to: 1
                  total: 24926
                  last-page: 24926
              links:
                first: https://www.saveecobot.com/api/v1/cities?page%5Bnumber%5D=1&page%5Bsize%5D=1
                next: https://www.saveecobot.com/api/v1/cities?page%5Bnumber%5D=2&page%5Bsize%5D=1
                last: https://www.saveecobot.com/api/v1/cities?page%5Bnumber%5D=24926&page%5Bsize%5D=1
              data:
              - type: cities
                id: '1'
                attributes:
                  city_name: Дніпро
                  hromada_name: Дніпpoвськa міська громада
                  hromada_id: 1188
                  region_name: Дніпропетровська область
                  region_id: 4
                  is_hide_region: false
                  is_regional_center: true
                  type_name: місто
                  aqi: 29
                  aqi_is_old: true
                  aqi_updated_at: '2025-01-07T09:00:00.000000Z'
                  cnt_devices_with_aqi: 0
                  center_latitude: '48.464717'
                  center_longitude: '35.046183'
                  rating_aqi: 
                  information_title: Середній індекс якості повітря по місту
                  information_text: Індекс якості атмосферного повітря, розрахований за формулою NowCast (US EPA) для головного забрудника повітря – дрібнодисперсного пилу фракції PM2.5.
                  link_logo: https://www.saveecobot.com/maps#12/48.464717/35.046183
                  link_maps_aqi: https://www.saveecobot.com/maps#12/48.464717/35.046183
                  link_maps_gamma: https://www.saveecobot.com/radiation-maps#12/48.464717/35.046183
                  link: https://www.saveecobot.com/maps/dnipro
                relationships:
                  city-districts:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/1/relationships/city-districts
                      related: https://www.saveecobot.com/api/v1/cities/1/city-districts
                  sensors:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/1/relationships/sensors
                      related: https://www.saveecobot.com/api/v1/cities/1/sensors
                  hourly-data:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/1/relationships/hourly-data
                      related: https://www.saveecobot.com/api/v1/cities/1/hourly-data
                links:
                  self: https://www.saveecobot.com/api/v1/cities/1
          schema:
            type: object
            properties:
              meta:
                "$ref": "#/definitions/PaginationMeta"
              links:
                "$ref": "#/definitions/PaginationLinks"
              data:
                type: array
                items:
                  "$ref": "#/definitions/Населений пункт"
            required:
            - meta
            - links
            - data
      operationId: get-cities
  "/cities/{city_id}":
    get:
      tags:
      - Населені пункти
      summary: Інформація про населений пункт
      description: Отримання інформації про населений пункт з посиланнями на перелік станцій моніторингу, поточні дані якості повітря у населеному пункті, архів даних, та іншу додаткову інформацію пов'язану з населеним пунктом.
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
                type: cities
                id: '308'
                attributes:
                  city_name: Полтава
                  hromada_name: Пoлтaвськa міська громада
                  hromada_id: 347
                  region_name: Полтавська область
                  region_id: 16
                  is_hide_region: false
                  is_regional_center: true
                  type_name: місто
                  aqi: 34
                  aqi_is_old: true
                  aqi_updated_at: '2023-12-11T09:00:00.000000Z'
                  cnt_devices_with_aqi: 0
                  center_latitude: '49.58826699999999'
                  center_longitude: '34.5514169'
                  rating_aqi: 
                  meteo:
                    wind_power:
                      value: 2
                      updated_at: '2026-05-02 12:00:00'
                      is_old: true
                    wind_direction:
                      value: NE
                      updated_at: '2026-05-02 12:00:00'
                      is_old: true
                    wind_direction_grad:
                      value: 45
                      updated_at: '2022-08-24 21:00:00'
                      is_old: true
                    temperature:
                      value: 10.7
                      updated_at: '2026-05-02 12:00:00'
                      is_old: true
                    humidity:
                      value: 35
                      updated_at: '2026-05-02 12:00:00'
                      is_old: true
                    pressure:
                      value: 1020.2
                      updated_at: '2022-08-24 21:00:00'
                      is_old: true
                    pressure_pa:
                      value: 1006584.12
                      updated_at: '2026-05-02 12:00:00'
                      is_old: true
                    gamma:
                      value: 122
                      updated_at: '2026-07-15T16:46:06.000000Z'
                      is_old: true
                      device_id: 25846
                      platform_id: 95
                      platform_name: SaveDnipro & Safecast
                  information_title: Середній індекс якості повітря по місту
                  information_text: Індекс якості атмосферного повітря, розрахований за формулою NowCast (US EPA) для головного забрудника повітря – дрібнодисперсного пилу фракції PM2.5.
                  link_logo: https://www.saveecobot.com/maps#12/49.58826699999999/34.5514169
                  link_maps_aqi: https://www.saveecobot.com/maps#12/49.58826699999999/34.5514169
                  link_maps_gamma: https://www.saveecobot.com/radiation-maps#12/49.58826699999999/34.5514169
                  link: https://www.saveecobot.com/maps/poltava
                relationships:
                  city-districts:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/308/relationships/city-districts
                      related: https://www.saveecobot.com/api/v1/cities/308/city-districts
                  sensors:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/308/relationships/sensors
                      related: https://www.saveecobot.com/api/v1/cities/308/sensors
                  hourly-data:
                    links:
                      self: https://www.saveecobot.com/api/v1/cities/308/relationships/hourly-data
                      related: https://www.saveecobot.com/api/v1/cities/308/hourly-data
                links:
                  self: https://www.saveecobot.com/api/v1/cities/308
          schema:
            type: object
            properties:
              data:
                "$ref": "#/definitions/Населений пункт"
            required:
            - data
      operationId: get-city-information
  "/sensors":
    get:
      tags:
      - Cтанції моніторингу
      summary: Пошук станцій моніторингу
      description: |-
        Отримання переліку станцій моніторингу з можливістю фільтрації по типу станції моніторингу.

        Нові станції відображаються на початку, для того, щоб можна було швидко отримувати їх.
      parameters:
      - name: filter[type_id]
        in: query
        description: Тип станції моніторингу
        type: number
        enum:
        - 1
        - 2
        - 3
        - 4
      - name: page[size]
        in: query
        description: Кількість записів на сторінці
        required: false
        type: number
        default: 100
        minimum: 1
        maximum: 100
        allowEmptyValue: true
      - name: page[number]
        in: query
        description: Номер сторінки
        required: false
        type: number
        default: 1
        allowEmptyValue: true
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              meta:
                "$ref": "#/definitions/PaginationMeta"
              links:
                "$ref": "#/definitions/PaginationLinks"
              data:
                type: array
                items:
                  "$ref": "#/definitions/Станція моніторингу"
            required:
            - meta
            - links
            - data
          examples:
            application/json:
              meta:
                page:
                  current-page: 1
                  per-page: 1
                  from: 1
                  to: 1
                  total: 2952
                  last-page: 2952
              links:
                first: https://www.saveecobot.com/api/v1/sensors?page%5Bnumber%5D=1&page%5Bsize%5D=1
                next: https://www.saveecobot.com/api/v1/sensors?page%5Bnumber%5D=2&page%5Bsize%5D=1
                last: https://www.saveecobot.com/api/v1/sensors?page%5Bnumber%5D=2952&page%5Bsize%5D=1
              data:
              - type: sensors
                id: '25999'
                attributes:
                  external_id: 
                  longitude: '34.488202'
                  latitude: '49.587528'
                  district_id: 
                  district_name: 
                  city_id: 308
                  city_type_name: місто
                  city_name: Полтава
                  hromada_id: 
                  hromada_katottg_code: 
                  hromada_koatuu_code: 
                  hromada_name: 
                  hromada_full_name: 
                  hromada_type_name: 
                  region_district_id: 
                  region_district_name: 
                  region_id: 16
                  region_name: Полтавська область
                  country_id: 1
                  country_name: Україна
                  sensor_name: Район вулиць Чумацький шлях, Кузьми Скрябіна та провулку Космічний (ПСШ №40 ПМР)
                  sensor_notes: 
                  sensor_installation_partners: 
                  type_id: 1
                  type_name: Станція моніторингу якості повітря
                  platform_id: 126
                  platform_name: Полтавська міська рада
                  aqi: 29
                  aqi_is_old: false
                  aqi_updated_at: '2026-07-27T09:00:00.000000Z'
                  created_at: '2026-07-27 07:40:08'
                  last_measurement_at: '2026-07-27T09:59:00.000000Z'
                  measurements_count: 24
                  information_title: Індекс якості повітря з певної станції
                  information_text: Індекс якості атмосферного повітря, розрахований за формулою NowCast (US EPA) для головного забрудника повітря – дрібнодисперсного пилу фракції PM2.5.
                  link_logo: https://www.saveecobot.com/station/25999
                  link_maps_aqi: https://www.saveecobot.com/maps#13/49.587528/34.488202
                  link_maps_gamma: https://www.saveecobot.com/radiation-maps#13/49.587528/34.488202
                  link: https://www.saveecobot.com/station/25999
                relationships:
                  last-data:
                    links:
                      related: https://www.saveecobot.com/api/v1/sensors/25999/last-data
                  hourly-data:
                    links:
                      related: https://www.saveecobot.com/api/v1/sensors/25999/hourly-data
                links:
                  data-archive: https://www.saveecobot.com/api/v1/sensor-archives/25999
                  data-archive-list: https://www.saveecobot.com/api/v1/sensor-archives/25999/list
                  data-hourly-archives: https://www.saveecobot.com/api/v1/sensor-hourly-archives/25999
                  platforms: https://www.saveecobot.com/api/v1/platforms/126
                  cities: https://www.saveecobot.com/api/v1/cities/308
                  regions: https://www.saveecobot.com/api/v1/regions/16
                  self: https://www.saveecobot.com/api/v1/sensors/25999
        '401':
          description: No API key found in request or invalid authentication credentials
        '503':
          description: The service is unavailable.
        '504':
          description: Gateway Timeout
          schema:
            type: object
            properties: {}
      operationId: get-sensors
    parameters: []
  "/sensors/{sensor_id}":
    get:
      tags:
      - Cтанції моніторингу
      summary: Інформація про станцію моніторингу
      description: Отримання інформації про станцію моніторингу з посиланнями на дані замірів, архів даних, та іншу додаткову інформацію пов'язану зі станцією.
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
                type: sensors
                id: '25999'
                attributes:
                  external_id: 
                  longitude: '34.488202'
                  latitude: '49.587528'
                  district_id: 
                  district_name: 
                  city_id: 308
                  city_type_name: місто
                  city_name: Полтава
                  hromada_id: 
                  hromada_katottg_code: 
                  hromada_koatuu_code: 
                  hromada_name: 
                  hromada_full_name: 
                  hromada_type_name: 
                  region_district_id: 
                  region_district_name: 
                  region_id: 16
                  region_name: Полтавська область
                  country_id: 1
                  country_name: Україна
                  sensor_name: Район вулиць Чумацький шлях, Кузьми Скрябіна та провулку Космічний (ПСШ №40 ПМР)
                  sensor_notes: 
                  sensor_installation_partners: 
                  type_id: 1
                  type_name: Станція моніторингу якості повітря
                  platform_id: 126
                  platform_name: Полтавська міська рада
                  aqi: 29
                  aqi_is_old: false
                  aqi_updated_at: '2026-07-27T09:00:00.000000Z'
                  created_at: '2026-07-27 07:40:08'
                  last_measurement_at: '2026-07-27T09:59:00.000000Z'
                  measurements_count: 24
                  information_title: Індекс якості повітря з певної станції
                  information_text: Індекс якості атмосферного повітря, розрахований за формулою NowCast (US EPA) для головного забрудника повітря – дрібнодисперсного пилу фракції PM2.5.
                  link_logo: https://www.saveecobot.com/station/25999
                  link_maps_aqi: https://www.saveecobot.com/maps#13/49.587528/34.488202
                  link_maps_gamma: https://www.saveecobot.com/radiation-maps#13/49.587528/34.488202
                  link: https://www.saveecobot.com/station/25999
                relationships:
                  last-data:
                    links:
                      related: https://www.saveecobot.com/api/v1/sensors/25999/last-data
                  hourly-data:
                    links:
                      related: https://www.saveecobot.com/api/v1/sensors/25999/hourly-data
                links:
                  data-archive: https://www.saveecobot.com/api/v1/sensor-archives/25999
                  data-archive-list: https://www.saveecobot.com/api/v1/sensor-archives/25999/list
                  data-hourly-archives: https://www.saveecobot.com/api/v1/sensor-hourly-archives/25999
                  platforms: https://www.saveecobot.com/api/v1/platforms/126
                  cities: https://www.saveecobot.com/api/v1/cities/308
                  regions: https://www.saveecobot.com/api/v1/regions/16
                  self: https://www.saveecobot.com/api/v1/sensors/25999
          schema:
            type: object
            properties:
              data:
                "$ref": "#/definitions/Станція моніторингу"
            required:
            - data
          headers: {}
      operationId: get-sensor-information
    parameters:
    - type: integer
      name: sensor_id
      in: path
      description: Унікальний ідентифікатор (ID) станцій моніторингу
      required: true
  "/sensor-types":
    get:
      summary: Перелік типів станцій моніторингу.
      tags:
      - Cтанції моніторингу
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              meta:
                "$ref": "#/definitions/PaginationMeta"
              links:
                "$ref": "#/definitions/PaginationLinks"
              data:
                type: array
                items:
                  "$ref": "#/definitions/Тип станції моніторингу"
            required:
            - meta
            - links
            - data
          examples:
            application/json:
              meta:
                page:
                  current-page: 1
                  per-page: 2
                  from: 1
                  to: 2
                  total: 5
                  last-page: 3
              links:
                first: https://www.saveecobot.com/api/v1/sensor-types?page%5Bnumber%5D=1&page%5Bsize%5D=2
                next: https://www.saveecobot.com/api/v1/sensor-types?page%5Bnumber%5D=2&page%5Bsize%5D=2
                last: https://www.saveecobot.com/api/v1/sensor-types?page%5Bnumber%5D=3&page%5Bsize%5D=2
              data:
              - type: sensor-types
                id: '1'
                attributes:
                  type_name: Станція моніторингу якості повітря
                links:
                  self: https://www.saveecobot.com/api/v1/sensor-types/1
              - type: sensor-types
                id: '2'
                attributes:
                  type_name: Метеорологічна станція
                links:
                  self: https://www.saveecobot.com/api/v1/sensor-types/2
          headers: {}
      operationId: get-sensor-types
      description: Отримання переліку типів станцій моніторингу.
  "/sensor-last-data":
    get:
      summary: Останні первинні дані усіх станцій моніторингу
      tags:
      - Cтанції моніторингу
      operationId: get-sensor-last-data
      description: Отримання переліку останніх даних усіх станцій моніторингу.
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/Останні дані станції моніторингу"
            required:
            - data
          examples:
            application/json:
              data:
              - type: sensor-last-data
                id: ''
                attributes:
                  sensor_id: 1
                  phenomenon: pm25
                  value: 1.6
                  is_old: false
                  updated_at_local: '2026-06-25 20:35:04'
                  updated_at: '2026-06-25T17:35:04Z'
              - type: sensor-last-data
                id: ''
                attributes:
                  sensor_id: 1
                  phenomenon: pm10
                  value: 3.17
                  is_old: false
                  updated_at_local: '2026-06-25 20:35:04'
                  updated_at: '2026-06-25T17:35:04Z'
  "/sensor-archives/{sensor_id}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
    get:
      summary: Останній архів даних станції моніторингу
      tags:
      - Cтанції моніторингу
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP-архів із CSV-файлом
          schema:
            type: file
        '404':
          description: Архів не знайдено
        '503':
          description: Архівні дані тимчасово недоступні
      operationId: get-sensor-archives-sensor_id
      description: |-
        Отримання останнього доступного архіву первинних даних станції моніторингу.

        Цей endpoint повертає останній доступний архів, окрім плаваючого файлу за останні 7 днів.
  "/sensor-archives/{sensor_id}/list":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
    get:
      summary: Перелік усіх архівів даних станції моніторингу
      tags:
      - Cтанції моніторингу
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                "$ref": "#/definitions/Перелік архівів станції моніторингу"
            required:
            - data
          examples:
            application/json:
              data:
                type: sensor-archive-lists
                id: '1'
                attributes:
                  device_id: 1
                  archives:
                  - period_key: 2019-2025
                    year: 
                    kind: raw_bundle
                    is_bundle: true
                    is_latest: false
                    is_raw: true
                    date_from: '2019-02-27'
                    date_to: '2025-12-31'
                    format: zip
                    rows_count: 10537634
                    file_size_bytes: 49414914
                    download_url: https://www.saveecobot.com/api/v1/sensor-archives/1/periods/2019-2025
                  - period_key: '2026'
                    year: 2026
                    kind: raw_year
                    is_bundle: false
                    is_latest: true
                    is_raw: true
                    date_from: '2026-01-01'
                    date_to: '2026-04-10'
                    format: zip
                    rows_count: 450960
                    file_size_bytes: 2174094
                    download_url: https://www.saveecobot.com/api/v1/sensor-archives/1/years/2026
                links:
                  self: https://www.saveecobot.com/api/v1/sensor-archives/1/list
                  data-archive: https://www.saveecobot.com/api/v1/sensor-archives/1
                  data-hourly-archives: https://www.saveecobot.com/api/v1/sensor-hourly-archives/1
        '404':
          description: Станцію не знайдено
        '503':
          description: Архівні дані тимчасово недоступні
      operationId: get-sensor-archives-list-sensor_id
      description: |-
        Отримання переліку всіх доступних архівів станції моніторингу.

        У список не входить плаваючий архів за останні 7 днів.

        Для завершених років API може повертати як окремі річні ZIP-архіви, так і один historical bundle з period key на кшталт `2019-2024`.
  "/sensor-archives/{sensor_id}/years/{year}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
    - type: integer
      name: year
      in: path
      required: true
    get:
      summary: Архів даних станції моніторингу за конкретний рік
      tags:
      - Cтанції моніторингу
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP-архів із CSV-файлом за вказаний рік
          schema:
            type: file
        '404':
          description: Архів за цей рік не знайдено
        '503':
          description: Архівні дані тимчасово недоступні
      operationId: get-sensor-archives-year-sensor_id
      description: Отримання архіву первинних даних станції моніторингу за конкретний рік.
  "/sensor-archives/{sensor_id}/periods/{period_key}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
    - type: string
      name: period_key
      in: path
      required: true
    get:
      summary: Архів даних станції моніторингу за нерічний період
      tags:
      - Cтанції моніторингу
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP-архів із CSV-файлом за вказаний період
          schema:
            type: file
        '404':
          description: Архів за цей період не знайдено
        '503':
          description: Архівні дані тимчасово недоступні
      operationId: get-sensor-archives-period-sensor_id
      description: |-
        Отримання архіву первинних даних станції моніторингу за нерічний період.

        Наприклад, для `before_2019` або historical bundle `2019-2024`.
  "/sensors/{sensor_id}/last-data":
    parameters:
    - type: integer
      name: sensor_id
      in: path
      required: true
    get:
      summary: Первинні дані станції моніторингу
      tags:
      - Cтанції моніторингу
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/Останні дані станції моніторингу"
            required:
            - data
          examples:
            application/json:
              data:
              - type: sensor-last-data
                id: ''
                attributes:
                  sensor_id: 25999
                  phenomenon: co_mg
                  value: 0.0001
                  updated_at: '2026-07-27T08:59:00.000000Z'
                  is_old: 0
              - type: sensor-last-data
                id: ''
                attributes:
                  sensor_id: 25999
                  phenomenon: co_ppm
                  value: 0.0001
                  updated_at: '2026-07-27T08:59:00.000000Z'
                  is_old: 0
      operationId: get-sensors-sensor_id-sensor-last-data
      description: |-
        Отримання переліку останніх даних станції моніторингу по кожному з вимірюваних параметрів.

        Перелік параметрів можно переглянути у запиті `GET /phenomenons`.
  "/sensors/{sensor_id}/hourly-data":
    parameters:
    - type: integer
      name: sensor_id
      in: path
      required: true
    - type: integer
      name: page[size]
      in: query
      required: false
      default: 48
      minimum: 1
      maximum: 100
      description: Кількість погодинних записів у відповіді.
    get:
      summary: Розраховані щогодинні дані станції моніторингу
      tags:
      - Cтанції моніторингу
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - type: sensor-hourly-data
                id: ''
                attributes:
                  sensor_id: 25999
                  phenomenon: aqi
                  value: 29
                  value_sum: 
                  value_cnt: 
                  logged_at: '2026-07-27 09:00:00'
              - type: sensor-hourly-data
                id: ''
                attributes:
                  sensor_id: 25999
                  phenomenon: aqi
                  value: 32
                  value_sum: 
                  value_cnt: 
                  logged_at: '2026-07-27 08:00:00'
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/Щогодинні дані станції моніторингу"
            required:
            - data
        '404':
          description: Станцію не знайдено
      operationId: get-sensors-sensor_id-hourly-data
      description: |-
        Отримання останніх розрахованих щогодинних даних станції моніторингу.

        Endpoint повертає лише актуальне recent-вікно з warm storage, а не повний історичний архів.
  "/sensor-hourly-archives/{sensor_id}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
    get:
      summary: Архів розрахованих щогодинних даних станції моніторингу
      tags:
      - Cтанції моніторингу
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP-архів із CSV-файлом
          schema:
            type: file
        '404':
          description: Архів не знайдено
        '503':
          description: Архівні дані тимчасово недоступні
      operationId: get-sensor-hourly-archives-sensor_id
      description: |-
        Отримання готового ZIP-архіву з розрахованими щогодинними даними станції моніторингу.

        Архів перебудовується щоденно вночі і не генерується на льоту.
  "/phenomenons":
    get:
      summary: Перелік вимірюванних параметрів
      tags:
      - Cтанції моніторингу
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - phenomenon: pm
                label: Пил
                unit: мкг/м³
                format: "%0.1f"
                emoji: "☁️"
              - phenomenon: pm1
                label: PM1
                unit: мкг/м³
                format: "%0.1f"
                emoji: "☁️"
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/Вимірюваний параметр"
            required:
            - data
      operationId: get-phenomenons
      description: Отримання перелік вимірюванних параметрів станціями моніторингу, з вказанням їх кодів, за якими вони відображаються в первинних даних, а також одиниці вимірювання.
  "/aqi-ukraine/sensors-last-data":
    get:
      summary: Останні AQI дані усіх публічних станцій України
      tags:
      - AQI Ukraine
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - sensor_id: 25999
                updated_at: '2026-07-27T09:00:00.000000Z'
                aqi_pm25: 29
                is_old: false
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/AqiLastData"
            required:
            - data
      operationId: get-aqi-ukraine-sensors-last-data
      description: Повертає компактний список останніх AQI PM2.5 NowCast (US EPA) значень для публічних станцій України.
  "/aqi-ukraine/sensors-last-data-with-history":
    get:
      summary: Останні AQI дані усіх публічних станцій України з історією
      tags:
      - AQI Ukraine
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - sensor_id: 25999
                updated_at: '2026-07-27T09:00:00.000000Z'
                aqi_pm25: 29
                is_old: false
                history:
                - datetime: '2026-07-27 09:00:00'
                  aqi_pm25: 29
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/AqiLastDataWithHistory"
            required:
            - data
      operationId: get-aqi-ukraine-sensors-last-data-with-history
      description: Повертає останні AQI PM2.5 NowCast (US EPA) значення та коротку історію для публічних станцій України.
  "/aqi-ukraine/sensors-details":
    get:
      summary: Деталі публічних AQI станцій України
      tags:
      - AQI Ukraine
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        description: Мова локалізованих назв у відповіді.
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - sensor_id: 25999
                sensor_name: Район вулиць Чумацький шлях, Кузьми Скрябіна та провулку Космічний (ПСШ №40 ПМР)
                latitude: '49.587528'
                longitude: '34.488202'
                region_name: Полтавська область
                city_type_name: місто
                city_name: Полтава
                platform_name: Полтавська міська рада
                url_maps: https://www.saveecobot.com/maps#13/49.587528/34.488202
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/AqiSensorDetails"
            required:
            - data
      operationId: get-aqi-ukraine-sensors-details
      description: Повертає координати, назви та службові поля публічних станцій, для яких доступні AQI дані.
  "/aqi-ukraine/sensor-last-data/{sensor_id}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Ідентифікатор станції моніторингу.
    get:
      summary: Останні AQI дані однієї публічної станції
      tags:
      - AQI Ukraine
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
              - phenomenon: aqi_pm25
                value: 29
                unit: ''
                format: "%d"
                emoji: ''
                updated_at: '2026-07-27T09:00:00.000000Z'
                is_old: 0
              - phenomenon: co_mg
                value: 0.0001
                unit: мг/м³
                format: "%0.2f"
                emoji: "\U0001F4AD"
                updated_at: '2026-07-27T08:59:00.000000Z'
                is_old: 0
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/AqiSingleSensorValue"
            required:
            - data
        '403':
          description: Станція недоступна для публічного API
        '404':
          description: Станцію не знайдено
      operationId: get-aqi-ukraine-sensor-last-data-sensor_id
      description: Повертає останні AQI показники конкретної публічної станції.
definitions:
  PaginationMeta:
    type: object
    properties:
      page:
        type: object
        properties:
          current-page:
            type: integer
          per-page:
            type: integer
          from:
            type: integer
            x-nullable: true
          to:
            type: integer
            x-nullable: true
          total:
            type: integer
          last-page:
            type: integer
  PaginationLinks:
    type: object
    properties:
      first:
        type: string
        format: uri
      prev:
        type: string
        format: uri
        x-nullable: true
      next:
        type: string
        format: uri
        x-nullable: true
      last:
        type: string
        format: uri
  JsonApiRelatedLinks:
    type: object
    properties:
      self:
        type: string
        format: uri
      related:
        type: string
        format: uri
  Населений пункт:
    type: object
    properties:
      type:
        type: string
        example: cities
      id:
        type: string
      attributes:
        type: object
        properties:
          city_name:
            type: string
          hromada_name:
            type: string
            x-nullable: true
          hromada_id:
            type: integer
            x-nullable: true
          region_name:
            type: string
          region_id:
            type: integer
          is_hide_region:
            type: boolean
          is_regional_center:
            type: boolean
          type_name:
            type: string
          aqi:
            type: integer
            x-nullable: true
          aqi_is_old:
            type: boolean
          aqi_updated_at:
            type: string
            format: date-time
            x-nullable: true
          cnt_devices_with_aqi:
            type: integer
          center_latitude:
            type: string
            x-nullable: true
          center_longitude:
            type: string
            x-nullable: true
          rating_aqi:
            type: integer
            x-nullable: true
          meteo:
            type: object
            additionalProperties: true
          information_title:
            type: string
            x-nullable: true
          information_text:
            type: string
            x-nullable: true
          link_logo:
            type: string
            format: uri
            x-nullable: true
          link_maps_aqi:
            type: string
            format: uri
            x-nullable: true
          link_maps_gamma:
            type: string
            format: uri
            x-nullable: true
          link:
            type: string
            format: uri
            x-nullable: true
      relationships:
        type: object
        additionalProperties:
          "$ref": "#/definitions/JsonApiRelatedLinks"
      links:
        type: object
        additionalProperties:
          type: string
          format: uri
    required:
    - type
    - id
    - attributes
  Станція моніторингу:
    type: object
    properties:
      type:
        type: string
        example: sensors
      id:
        type: string
      attributes:
        type: object
        properties:
          external_id:
            type: string
            x-nullable: true
          longitude:
            type: string
          latitude:
            type: string
          district_id:
            type: integer
            x-nullable: true
          district_name:
            type: string
            x-nullable: true
          city_id:
            type: integer
            x-nullable: true
          city_type_name:
            type: string
            x-nullable: true
          city_name:
            type: string
            x-nullable: true
          hromada_id:
            type: integer
            x-nullable: true
          hromada_katottg_code:
            type: string
            x-nullable: true
          hromada_koatuu_code:
            type: string
            x-nullable: true
          hromada_name:
            type: string
            x-nullable: true
          hromada_full_name:
            type: string
            x-nullable: true
          hromada_type_name:
            type: string
            x-nullable: true
          region_district_id:
            type: integer
            x-nullable: true
          region_district_name:
            type: string
            x-nullable: true
          region_id:
            type: integer
            x-nullable: true
          region_name:
            type: string
            x-nullable: true
          country_id:
            type: integer
            x-nullable: true
          country_name:
            type: string
            x-nullable: true
          sensor_name:
            type: string
          sensor_notes:
            type: string
            x-nullable: true
          sensor_installation_partners:
            type: string
            x-nullable: true
          type_id:
            type: integer
            x-nullable: true
          type_name:
            type: string
          platform_id:
            type: integer
            x-nullable: true
          platform_name:
            type: string
            x-nullable: true
          aqi:
            type: integer
            x-nullable: true
          aqi_is_old:
            type: boolean
          aqi_updated_at:
            type: string
            format: date-time
            x-nullable: true
          created_at:
            type: string
            x-nullable: true
          last_measurement_at:
            type: string
            format: date-time
            x-nullable: true
          measurements_count:
            type: integer
          information_title:
            type: string
            x-nullable: true
          information_text:
            type: string
            x-nullable: true
          link_logo:
            type: string
            format: uri
            x-nullable: true
          link_maps_aqi:
            type: string
            format: uri
            x-nullable: true
          link_maps_gamma:
            type: string
            format: uri
            x-nullable: true
          link:
            type: string
            format: uri
            x-nullable: true
      relationships:
        type: object
        additionalProperties:
          "$ref": "#/definitions/JsonApiRelatedLinks"
      links:
        type: object
        additionalProperties:
          type: string
          format: uri
    required:
    - type
    - id
    - attributes
  Тип станції моніторингу:
    type: object
    properties:
      type:
        type: string
        example: sensor-types
      id:
        type: string
      attributes:
        type: object
        properties:
          type_name:
            type: string
      links:
        type: object
        additionalProperties:
          type: string
          format: uri
    required:
    - type
    - id
    - attributes
  Останні дані станції моніторингу:
    type: object
    properties:
      type:
        type: string
        example: sensor-last-data
      id:
        type: string
      attributes:
        type: object
        properties:
          sensor_id:
            type: integer
          phenomenon:
            type: string
          value:
            type: number
            format: float
            x-nullable: true
          is_old:
            type: boolean
          updated_at_local:
            type: string
            x-nullable: true
          updated_at:
            type: string
            format: date-time
    required:
    - type
    - id
    - attributes
  Щогодинні дані станції моніторингу:
    type: object
    properties:
      type:
        type: string
        example: sensor-hourly-data
      id:
        type: string
      attributes:
        type: object
        properties:
          sensor_id:
            type: integer
          phenomenon:
            type: string
          value:
            type: number
            format: float
            x-nullable: true
          value_sum:
            type: number
            format: float
            x-nullable: true
          value_cnt:
            type: integer
            x-nullable: true
          logged_at:
            type: string
  Вимірюваний параметр:
    type: object
    properties:
      phenomenon:
        type: string
      label:
        type: string
      unit:
        type: string
      format:
        type: string
      emoji:
        type: string
  Архівний період станції моніторингу:
    type: object
    properties:
      period_key:
        type: string
      year:
        type: integer
        x-nullable: true
      kind:
        type: string
        enum:
        - raw_year
        - raw_bundle
        - raw_before_2019
        - hourly_all_time
        - raw_period
      is_bundle:
        type: boolean
      is_latest:
        type: boolean
      is_raw:
        type: boolean
      date_from:
        type: string
        format: date
        x-nullable: true
      date_to:
        type: string
        format: date
        x-nullable: true
      format:
        type: string
        example: zip
      rows_count:
        type: integer
        x-nullable: true
      file_size_bytes:
        type: integer
        x-nullable: true
      download_url:
        type: string
        format: uri
    required:
    - period_key
    - format
    - download_url
  Перелік архівів станції моніторингу:
    type: object
    properties:
      type:
        type: string
        example: sensor-archive-lists
      id:
        type: string
      attributes:
        type: object
        properties:
          device_id:
            type: integer
          archives:
            type: array
            items:
              "$ref": "#/definitions/Архівний період станції моніторингу"
      links:
        type: object
        additionalProperties:
          type: string
          format: uri
  AqiLastData:
    type: object
    properties:
      sensor_id:
        type: integer
      updated_at:
        type: string
        format: date-time
      aqi_pm25:
        type: integer
      is_old:
        type: boolean
  AqiLastDataWithHistory:
    allOf:
    - "$ref": "#/definitions/AqiLastData"
    - type: object
      properties:
        history:
          type: array
          items:
            "$ref": "#/definitions/AqiHistoryPoint"
  AqiHistoryPoint:
    type: object
    properties:
      datetime:
        type: string
      aqi_pm25:
        type: integer
  AqiSensorDetails:
    type: object
    properties:
      sensor_id:
        type: integer
      sensor_name:
        type: string
      latitude:
        type: string
      longitude:
        type: string
      region_name:
        type: string
      city_type_name:
        type: string
      city_name:
        type: string
      platform_name:
        type: string
      url_maps:
        type: string
        format: uri
  AqiSingleSensorValue:
    type: object
    properties:
      phenomenon:
        type: string
      value:
        type: number
        format: float
        x-nullable: true
      unit:
        type: string
      format:
        type: string
      emoji:
        type: string
      updated_at:
        type: string
        format: date-time
      is_old:
        type: integer
        enum:
        - 0
        - 1
security:
- apikey: []
responses: {}
