---
swagger: '2.0'
info:
  version: '1.0'
  title: SaveEcoBot Air Quality Monitoring API
  description: SaveEcoBot is a Ukrainian environmental system that combines pollution data, polluter information, and environmental protection tools.<br/>This API provides air quality monitoring data collected and normalized by SaveEcoBot.<br/>For localized city, region, country, station type, and platform names, pass <code>filter[language]=en</code> where this filter is available.<br/>To get an access key, fill in <a href="https://forms.gle/r43qfvgmbrsqFkJD7" target="_blank">the request form</a>.
  contact:
    name: SaveDnipro
    email: savednipro@gmail.com
  termsOfService: https://www.saveecobot.com/en/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:
      - Places
      summary: Search places
      description: Returns places where monitoring stations are installed, with filters for region, country, community, regional-center flag, free-text query, and response language.
      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?filter%5Blanguage%5D=en&page%5Bnumber%5D=1&page%5Bsize%5D=1
                next: https://www.saveecobot.com/api/v1/cities?filter%5Blanguage%5D=en&page%5Bnumber%5D=2&page%5Bsize%5D=1
                last: https://www.saveecobot.com/api/v1/cities?filter%5Blanguage%5D=en&page%5Bnumber%5D=24926&page%5Bsize%5D=1
              data:
              - type: cities
                id: '1'
                attributes:
                  city_name: Dnipro
                  hromada_name: Dniprovska city community
                  hromada_id: 1188
                  region_name: Dnipropetrovsk Oblast
                  region_id: 4
                  is_hide_region: false
                  is_regional_center: true
                  type_name: city
                  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/en/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/City"
            required:
            - meta
            - links
            - data
      operationId: get-cities
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        default: en
        description: Response language for localized names. Use `en` to receive English city, region, country, station type, and platform names where translations are available.
  "/cities/{city_id}":
    get:
      tags:
      - Places
      summary: Place details
      description: Returns details for one place, including links to monitoring stations, current air quality data, hourly data, and related resources.
      responses:
        '200':
          description: OK
          examples:
            application/json:
              data:
                type: cities
                id: '308'
                attributes:
                  city_name: Poltava
                  hromada_name: Poltavska city community
                  hromada_id: 347
                  region_name: Poltava Oblast
                  region_id: 16
                  is_hide_region: false
                  is_regional_center: true
                  type_name: city
                  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/en/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/City"
            required:
            - data
      operationId: get-city-information
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        default: en
        description: Response language for localized names. Use `en` to receive English city, region, country, station type, and platform names where translations are available.
  "/sensors":
    get:
      tags:
      - Monitoring stations
      summary: Search monitoring stations
      description: |-
        Returns monitoring stations with filters for station type and response language.

        Newest stations are returned first so integrations can discover newly added stations quickly.
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        default: en
        description: Response language for localized names. Use `en` to receive English city, region, country, station type, and platform names where translations are available.
      - name: filter[type_id]
        in: query
        description: Monitoring station type ID.
        type: number
        enum:
        - 1
        - 2
        - 3
        - 4
      - name: page[size]
        in: query
        description: Number of records per page.
        required: false
        type: number
        default: 100
        minimum: 1
        maximum: 100
        allowEmptyValue: true
      - name: page[number]
        in: query
        description: Page number.
        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/MonitoringStation"
            required:
            - meta
            - links
            - data
          examples:
            application/json:
              meta:
                page:
                  current-page: 1
                  per-page: 1
                  from: 1
                  to: 1
                  total: 2951
                  last-page: 2951
              links:
                first: https://www.saveecobot.com/api/v1/sensors?filter%5Blanguage%5D=en&page%5Bnumber%5D=1&page%5Bsize%5D=1
                next: https://www.saveecobot.com/api/v1/sensors?filter%5Blanguage%5D=en&page%5Bnumber%5D=2&page%5Bsize%5D=1
                last: https://www.saveecobot.com/api/v1/sensors?filter%5Blanguage%5D=en&page%5Bnumber%5D=2951&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
                  city_name: Poltava
                  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: Poltava Oblast
                  country_id: 1
                  country_name: Ukraine
                  sensor_name: Raion vulyts Chumatskyi shliakh, Kuzmy Skriabina ta provulku Kosmichnyi (PSSh №40 PMR)
                  sensor_notes: 
                  sensor_installation_partners: 
                  type_id: 1
                  type_name: Air quality station
                  platform_id: 126
                  platform_name: Poltava City Council
                  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/en/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/en/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:
      - Monitoring stations
      summary: Monitoring station details
      description: Returns details for one monitoring station, including links to latest measurements, hourly data, archive files, platform, city, and region.
      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
                  city_name: Poltava
                  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: Poltava Oblast
                  country_id: 1
                  country_name: Ukraine
                  sensor_name: Raion vulyts Chumatskyi shliakh, Kuzmy Skriabina ta provulku Kosmichnyi (PSSh №40 PMR)
                  sensor_notes: 
                  sensor_installation_partners: 
                  type_id: 1
                  type_name: Air quality station
                  platform_id: 126
                  platform_name: Poltava City Council
                  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/en/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/en/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/MonitoringStation"
            required:
            - data
          headers: {}
      operationId: get-sensor-information
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        default: en
        description: Response language for localized names. Use `en` to receive English city, region, country, station type, and platform names where translations are available.
    parameters:
    - type: integer
      name: sensor_id
      in: path
      description: Monitoring station ID.
      required: true
  "/sensor-types":
    get:
      summary: Monitoring station types
      tags:
      - Monitoring stations
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              meta:
                "$ref": "#/definitions/PaginationMeta"
              links:
                "$ref": "#/definitions/PaginationLinks"
              data:
                type: array
                items:
                  "$ref": "#/definitions/MonitoringStationType"
            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: Returns the list of monitoring station types.
  "/sensor-last-data":
    get:
      summary: Latest raw data for all monitoring stations
      tags:
      - Monitoring stations
      operationId: get-sensor-last-data
      description: Returns the latest raw measurements from all monitoring stations.
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/SensorLastData"
            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
      description: Monitoring station ID.
    get:
      summary: Latest monitoring station data archive
      tags:
      - Monitoring stations
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP archive with a CSV file.
          schema:
            type: file
        '404':
          description: Archive not found.
        '503':
          description: Archive data is temporarily unavailable.
      operationId: get-sensor-archives-sensor_id
      description: |-
        Downloads the latest available ZIP archive with raw monitoring station data.

        This endpoint returns the latest available archive, excluding the rolling last-7-days file.
  "/sensor-archives/{sensor_id}/list":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    get:
      summary: List all monitoring station data archives
      tags:
      - Monitoring stations
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                "$ref": "#/definitions/SensorArchiveList"
            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: Station not found.
        '503':
          description: Archive data is temporarily unavailable.
      operationId: get-sensor-archives-list-sensor_id
      description: |-
        Returns all available archives for a monitoring station.

        The rolling archive for the last 7 days is not included.

        For completed years, the API may return separate yearly ZIP archives or one historical bundle with a period key such as `2019-2024`.
  "/sensor-archives/{sensor_id}/years/{year}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    - type: integer
      name: year
      in: path
      required: true
      description: Archive year.
    get:
      summary: Monitoring station data archive for a year
      tags:
      - Monitoring stations
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP archive with a CSV file for the requested year.
          schema:
            type: file
        '404':
          description: Archive for this year was not found.
        '503':
          description: Archive data is temporarily unavailable.
      operationId: get-sensor-archives-year-sensor_id
      description: Downloads a ZIP archive with raw monitoring station data for a specific year.
  "/sensor-archives/{sensor_id}/periods/{period_key}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    - type: string
      name: period_key
      in: path
      required: true
      description: Archive period key.
    get:
      summary: Monitoring station data archive for a custom period
      tags:
      - Monitoring stations
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP archive with a CSV file for the requested period.
          schema:
            type: file
        '404':
          description: Archive for this period was not found.
        '503':
          description: Archive data is temporarily unavailable.
      operationId: get-sensor-archives-period-sensor_id
      description: |-
        Downloads a ZIP archive with raw monitoring station data for a non-year period.

        For example, `before_2019` or a historical bundle such as `2019-2024`.
  "/sensors/{sensor_id}/last-data":
    parameters:
    - type: integer
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    get:
      summary: Latest raw data for one monitoring station
      tags:
      - Monitoring stations
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/SensorLastData"
            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: |-
        Returns the latest raw measurements for one monitoring station, grouped by measured parameter.

        Available parameter codes can be retrieved with `GET /phenomenons`.
  "/sensors/{sensor_id}/hourly-data":
    parameters:
    - type: integer
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    - type: integer
      name: page[size]
      in: query
      required: false
      default: 48
      minimum: 1
      maximum: 100
      description: Number of records per page.
    get:
      summary: Calculated hourly data for one monitoring station
      tags:
      - Monitoring stations
      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/SensorHourlyData"
            required:
            - data
        '404':
          description: Station not found.
      operationId: get-sensors-sensor_id-hourly-data
      description: |-
        Returns recent calculated hourly data for one monitoring station.

        This endpoint returns the current recent window from warm storage, not the full historical archive.
  "/sensor-hourly-archives/{sensor_id}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    get:
      summary: Calculated hourly data archive for one monitoring station
      tags:
      - Monitoring stations
      produces:
      - application/zip
      responses:
        '200':
          description: ZIP archive with a CSV file.
          schema:
            type: file
        '404':
          description: Archive not found.
        '503':
          description: Archive data is temporarily unavailable.
      operationId: get-sensor-hourly-archives-sensor_id
      description: |-
        Downloads a ZIP archive with calculated hourly data for one monitoring station.

        The archive is rebuilt every night and is not generated on the fly.
  "/phenomenons":
    get:
      summary: Measured parameter dictionary
      tags:
      - Monitoring stations
      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/Phenomenon"
            required:
            - data
      operationId: get-phenomenons
      description: Returns measured parameter codes used in raw data, together with display labels, units, formats, and icons.
  "/aqi-ukraine/sensors-last-data":
    get:
      summary: Latest AQI data for all public stations in Ukraine
      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: Returns a compact list of latest AQI PM2.5 NowCast (US EPA) values for public stations in Ukraine.
  "/aqi-ukraine/sensors-last-data-with-history":
    get:
      summary: Latest AQI data for all public stations in Ukraine with history
      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: Returns latest AQI PM2.5 NowCast (US EPA) values and short history for public stations in Ukraine.
  "/aqi-ukraine/sensors-details":
    get:
      summary: Public AQI station details in Ukraine
      tags:
      - AQI Ukraine
      parameters:
      - name: filter[language]
        in: query
        required: false
        type: string
        enum:
        - uk
        - en
        description: Response language for localized station names. Use `en` for English where translations are available.
        default: en
      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: Returns coordinates, names, and service fields for public stations that provide AQI data. Pass `filter[language]=en` for English localized names.
  "/aqi-ukraine/sensor-last-data/{sensor_id}":
    parameters:
    - type: string
      name: sensor_id
      in: path
      required: true
      description: Monitoring station ID.
    get:
      summary: Latest AQI data for one public station
      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: Station is not available through the public API.
        '404':
          description: Station not found.
      operationId: get-aqi-ukraine-sensor-last-data-sensor_id
      description: Returns latest AQI measurements for one public station.
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
  City:
    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
  MonitoringStation:
    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
  MonitoringStationType:
    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
  SensorLastData:
    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
  SensorHourlyData:
    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
  Phenomenon:
    type: object
    properties:
      phenomenon:
        type: string
      label:
        type: string
      unit:
        type: string
      format:
        type: string
      emoji:
        type: string
  SensorArchivePeriod:
    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
  SensorArchiveList:
    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/SensorArchivePeriod"
      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: {}
