API для разработчиков

Скачать OpenAPI 3.1 (JSON)← Открытые данные

Публичный REST API версии 1: чтение без ключей, JSON по умолчанию; приём данных станций — POST с ключом станции. Спецификация OpenAPI 3.1 генерируется из тех же схем, что проверяют запросы и ответы сервера.

Базовый адрес: https://havo.tj
Авторизация: Для чтения не требуется (ограничение 120 запросов в минуту с одного IP). Приём данных станций — заголовок Authorization: Bearer <ключ станции>, отдельный лимит 60 запросов в минуту на станцию.
CORS: Разрешены запросы с любых сайтов (Access-Control-Allow-Origin: *).

Качество воздуха

GET/api/v1/stationsкэш 60 s

Список станций мониторинга

Публичные станции (кроме выведенных из эксплуатации) как GeoJSON FeatureCollection с текущим уровнем индекса; 0 — нет данных или устарело.

Пример запроса

curl "https://havo.tj/api/v1/stations"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

type "FeatureCollection"обяз.
features object[]обяз.
- type "Feature"обяз.
- id integerобяз.
- geometry objectобяз.
  - type "Point"обяз.
  - coordinates [number, number]обяз.
- properties objectобяз.
  - id integerобяз.
  - slug stringобяз.
  - code stringобяз. — Station code, e.g. DU-01
  - name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
  - kind "air" | "meteo" | "combined"обяз.
  - status "active" | "suspended" | "decommissioned"обяз.
  - region object | nullобяз.
    tg string
    ru string
    en string
  - level integerобяз. — Air quality level 1–5 (1–6 for six-category scales such as US AQI); 0 — no data
  - indexValue number | nullобяз. — Continuous index value (level + fraction)
  - indexTime string (date-time) | nullобяз. — Time of the index value

GET/api/v1/stations/{slug}/measurementsкэш 60 s

Ряды измерений станции

Часовые (24h, 7d) или суточные по местному времени (30d, 1y) средние валидных измерений с min/max и числом значений. CSV — параметром format=csv. Значения и поле unit — в единице отображения, выбранной Агентством (µg/m³ или mg/m³).

Параметры
Параметр	Где	Тип	Описание
`slug`обяз.	path	string	Адрес станции (поле slug из списка станций)
`range`	query	24h \| 7d \| 30d \| 1y = 24h	Период: 24h, 7d, 30d или 1y
`pollutant`	query	string	Код вещества (PM25, PM10, NO2, SO2, CO, O3, NO, CH2O, C6H5OH, HF, TSP, CO2, TVOC); без параметра — все
`format`	query	json \| csv = json	json или csv

Пример запроса

curl "https://havo.tj/api/v1/stations/dushanbe-centre/measurements?range=7d&pollutant=PM25"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

station objectобяз.
- id integerобяз.
- slug stringобяз.
- code stringобяз.
- name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
  - tg string
  - ru string
  - en string
range "24h" | "7d" | "30d" | "1y"обяз.
from string (date-time)обяз. — ISO 8601 timestamp (UTC)
to string (date-time)обяз. — ISO 8601 timestamp (UTC)
aggregation "hour" | "day"обяз. — hour for 24h/7d, day (local time) for 30d/1y
timezone "Asia/Dushanbe"обяз.
series object[]обяз.
- pollutant objectобяз.
  - id integerобяз.
  - code stringобяз.
  - shortName stringобяз.
  - unit stringобяз. — Display unit configured by the Agency: µg/m³ or mg/m³ (CO always mg/m³; CO2 ppm, TVOC ppb). Values are converted to it
  - decimals integerобяз.
- points object[]обяз.
  - t string (date-time)обяз. — Start of the hour/day
  - v number | nullобяз. — Mean of valid measurements, in `unit`
  - min number | nullобяз.
  - max number | nullобяз.
  - n integerобяз. — Number of measurements in the bin

200text/csvCSV (UTF‑8 с BOM): time_utc, time_local, pollutant, value, min, max, n

400application/jsonНекорректные параметры

error stringобяз.

404application/jsonОбъект не найден

error stringобяз.

GET/api/v1/index/currentкэш 60 s

Текущий индекс по станциям

Последний рассчитанный индекс каждой публичной станции: уровень, значение, определяющее вещество, под‑индексы и признак устаревания (старше 6 часов). Для шкалы RATIO_TO_LIMIT — показатели методики Агентства (indicators): суммация NO₂+SO₂, максимальные разовые концентрации с кратностью ПДКм.р., признаки ВЗ/ЭВЗ; units — единицы отображения по веществам.

Параметры
Параметр	Где	Тип	Описание
`scale`	query	string	Код шкалы: NATIONAL_OPERATIONAL (по умолчанию), WHO_24H или IZA

Пример запроса

curl "https://havo.tj/api/v1/index/current"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

scale objectобяз.
- code stringобяз.
- kind "breakpoints" | "ratio_to_limit" | "iza"обяз.
- levels object[]обяз.
  - level integerобяз.
  - color stringобяз. — Hex colour
  - label objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
  - lo number
  - hi number | null
generatedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
units objectобяз. — Display unit per pollutant code (µg/m³ or mg/m³ as configured by the Agency; ppm, ppb)
stations object[]обяз.
- id integerобяз.
- slug stringобяз.
- code stringобяз.
- name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
  - tg string
  - ru string
  - en string
- level integerобяз. — Air quality level 1–5 (1–6 for six-category scales such as US AQI); 0 — no data
- value number | nullобяз.
- time string (date-time) | nullобяз.
- stale booleanобяз. — Index older than 6 hours
- dominantPollutant string | nullобяз. — Pollutant code with the worst sub-index
- subIndices objectобяз.
  - value numberобяз. — Concentration used for the sub-index, in the display unit
  - level integerобяз.
  - index numberобяз. — Continuous sub-index; for RATIO_TO_LIMIT — ratio to the daily limit
- indicators object | nullобяз.
  - no2so2Sum number | nullобяз. — NO2 + SO2 summation: sum of the daily-limit ratios; null when one of them is not measured
  - highPollution booleanобяз. — High pollution (ВЗ): a pollutant reached 10 single limits
  - extremeHighPollution booleanобяз. — Extremely high pollution (ЭВЗ): a pollutant reached 50 single limits
  - maxSingle objectобяз.
    value numberобяз. — Maximum single (hourly) concentration of the last 24 hours, in the display unit
    ratio number | nullобяз. — Ratio to the single limit; null without a limit
  - flagged objectобяз. — Pollutants with high/extremely high pollution: ratio to the single limit

404application/jsonОбъект не найден

error stringобяз.

GET/api/v1/exceedancesкэш 60 s

Активные превышения порогов

Открытые события превышения по правилам уведомлений Агентства (канал «портал»).

Пример запроса

curl "https://havo.tj/api/v1/exceedances"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

generatedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
events object[]обяз.
- id integerобяз.
- startedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
- station objectобяз.
  - id integerобяз.
  - slug stringобяз.
  - name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
- rule stringобяз.
- kind "pollutant" | "index"обяз.
- pollutant string | nullобяз.
- unit string | nullобяз.
- value number | nullобяз.
- threshold numberобяз.
- level integer | nullобяз.

Прогнозы

GET/api/v1/forecast/{slug}кэш 300 s

Прогноз погоды для точки

Почасовой ряд и суточные агрегаты SmartMet Server; время запуска модели и производитель данных.

Параметры
Параметр	Где	Тип	Описание
`slug`обяз.	path	string	Адрес точки прогноза, например dushanbe
`hours`	query	integer = 72	Число часов почасового ряда (1–240)
`days`	query	integer = 10	Число дней суточного прогноза (1–16)

Пример запроса

curl "https://havo.tj/api/v1/forecast/dushanbe?hours=48&days=7"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

location objectобяз.
- slug stringобяз.
- name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
  - tg string
  - ru string
  - en string
- lat numberобяз.
- lon numberобяз.
- region object | nullобяз.
  - tg string
  - ru string
  - en string
producer string | nullобяз. — SmartMet producer, e.g. ecmwf
originTime string (date-time) | nullобяз. — Model run time
fetchedAt string (date-time) | nullобяз.
timeZone "Asia/Dushanbe"обяз.
hourly object[]обяз.
- time string (date-time)обяз. — ISO 8601 timestamp (UTC)
- t number | null — Air temperature, °C
- ws number | null — Wind speed, m/s
- wd number | null — Wind direction, degrees
- gust number | null — Wind gust, m/s
- rh number | null — Relative humidity, %
- p number | null — Pressure, hPa
- dew number | null — Dew point, °C
- precip number | null — Precipitation, mm/h
- cloud number | null — Total cloud cover, %
- symbol integer | null — FMI SmartSymbol code (1xx — night variant)
daily object[]обяз.
- date string (date-time)обяз. — Local midnight (UTC+5) of the day
- tmax number | null
- tmin number | null
- precipSum number | null — Daily precipitation, mm
- ws number | null — Max wind speed, m/s
- cloud number | null
- symbol integer | null

404application/jsonОбъект не найден

error stringобяз.

GET/api/v1/silam/{slug}кэш 600 s

Прогноз качества воздуха SILAM для точки

Почасовые концентрации и уровни по веществам плюс суточная сводка (среднее за местные сутки, уровень по худшему веществу).

Параметры
Параметр	Где	Тип	Описание
`slug`обяз.	path	string	Адрес точки прогноза, например dushanbe

Пример запроса

curl "https://havo.tj/api/v1/silam/dushanbe"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

location objectобяз.
- slug stringобяз.
- name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
  - tg string
  - ru string
  - en string
- lat numberобяз.
- lon numberобяз.
run object | nullобяз.
- originTime string (date-time)обяз. — ISO 8601 timestamp (UTC)
- fetchedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
units objectобяз. — Unit per pollutant code
hourly objectобяз. — Hourly [time, value, level] per pollutant
days object[]обяз.
- date stringобяз. — YYYY-MM-DD, local time
- level integerобяз. — Air quality level 1–5 (1–6 for six-category scales such as US AQI); 0 — no data
- dominantPollutant string | nullобяз.
- means objectобяз. — Daily mean per pollutant code

404application/jsonОбъект не найден

error stringобяз.

GET/api/v1/silam/layersкэш 600 s

Каталог растровых слоёв SILAM

Границы сетки и PNG‑кадры по веществам и часам последнего прогона — для наложения на карту.

Пример запроса

curl "https://havo.tj/api/v1/silam/layers"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

run object | nullобяз.
- originTime string (date-time)обяз. — ISO 8601 timestamp (UTC)
- fetchedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
- hours integerобяз.
- bounds object | nullобяз. — Grid bounds in degrees for image placement
  - west numberобяз.
  - south numberобяз.
  - east numberобяз.
  - north numberобяз.
pollutants object[]обяз.
- code stringобяз.
- frames object[]обяз.
  - time string (date-time)обяз. — ISO 8601 timestamp (UTC)
  - url stringобяз. — Relative URL of the PNG layer
  - max number | nullобяз. — Maximum concentration in the domain

Предупреждения

GET/api/v1/alertsкэш 60 s

Предупреждения CAP

Нормализованный список предупреждений SmartMet Alert на выбранном языке (с фолбэком) или GeoJSON полигонов для карты.

Параметры
Параметр	Где	Тип	Описание
`active`	query	1	1 — только действующие сейчас
`region`	query	string	Код региона предупреждений (DU, SU, KT, GB, RRP)
`lang`	query	tg \| ru \| en = tg	Язык текстов: tg, ru или en
`days`	query	integer = 7	Горизонт в днях (1–14)
`format`	query	json \| geojson = json	json или geojson

Пример запроса

curl "https://havo.tj/api/v1/alerts?active=1&lang=ru"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

generatedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
lang "tg" | "ru" | "en"обяз.
count integerобяз.
alerts object[]обяз.
- id integerобяз.
- identifier stringобяз. — CAP identifier
- sent string (date-time)обяз. — ISO 8601 timestamp (UTC)
- msgType "Alert" | "Update" | "Cancel" | "Ack" | "Error"обяз.
- language stringобяз.
- event stringобяз.
- headline stringобяз.
- description string | nullобяз.
- instruction string | nullобяз.
- severity "Extreme" | "Severe" | "Moderate" | "Minor" | "Unknown"обяз.
- color "red" | "orange" | "yellow" | "none"обяз.
- colorHex stringобяз.
- urgency stringобяз.
- certainty stringобяз.
- effective string (date-time) | nullобяз.
- onset string (date-time) | nullобяз.
- expires string (date-time) | nullобяз.
- start string (date-time)обяз. — ISO 8601 timestamp (UTC)
- end string (date-time) | nullобяз.
- active booleanобяз.
- upcoming booleanобяз.
- regions object[]обяз.
  - code stringобяз.
  - name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
- areas string[]обяз. — areaDesc values
- web string | nullобяз.
- xml stringобяз. — URL of the original CAP XML

200application/geo+jsonGeoJSON при format=geojson

type "FeatureCollection"обяз.
generatedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
features object[]обяз.
- type "Feature"обяз.
- id stringобяз.
- geometry objectобяз.
  - type stringобяз.
  - coordinates any[]обяз.
- properties objectобяз.
  - id integerобяз.
  - identifier stringобяз.
  - event stringобяз.
  - headline stringобяз.
  - severity stringобяз.
  - level integerобяз.
  - color stringобяз.
  - start string (date-time)обяз. — ISO 8601 timestamp (UTC)
  - end string (date-time) | nullобяз.
  - active booleanобяз.
  - region string | nullобяз.
  - areaDesc stringобяз.
  - href stringобяз.

GET/api/v1/alerts/{id}/xmlкэш 300 s

Исходный CAP XML

Оригинальное сообщение CAP 1.2 (только status=Actual).

Параметры
Параметр	Где	Тип	Описание
`id`обяз.	path	string	Идентификатор предупреждения из списка

Пример запроса

curl "https://havo.tj/api/v1/alerts/1/xml"

Открыть в браузере → →

Ответы

200application/cap+xmlИсходное сообщение CAP 1.2

404application/jsonОбъект не найден

error stringобяз.

Новости

GET/api/v1/newsкэш 300 s

Новости

Опубликованные новости с анонсом, рубрикой, обложкой и ссылкой на страницу.

Параметры
Параметр	Где	Тип	Описание
`locale`	query	tg \| ru \| en = tg	Язык: tg, ru или en
`page`	query	integer = 1	Номер страницы
`pageSize`	query	integer = 12	Размер страницы (1–50)
`category`	query	string	Slug рубрики

Пример запроса

curl "https://havo.tj/api/v1/news?locale=ru&pageSize=5"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

locale "tg" | "ru" | "en"обяз.
page integerобяз.
pageSize integerобяз.
total integerобяз.
items object[]обяз.
- id integerобяз.
- slug stringобяз.
- title stringобяз.
- excerpt stringобяз.
- publishedAt string (date-time) | nullобяз.
- updatedAt string (date-time)обяз. — ISO 8601 timestamp (UTC)
- pinned booleanобяз.
- category object | nullобяз.
  - slug stringобяз.
  - name stringобяз.
- cover string | nullобяз. — Absolute URL of the cover image
- url stringобяз. — Absolute URL of the article

GET/api/v1/news/rss.xmlкэш 300 s

RSS новостей

20 последних новостей в RSS 2.0 на выбранном языке.

Параметры
Параметр	Где	Тип	Описание
`locale`	query	tg \| ru \| en = tg	Язык: tg, ru или en

Пример запроса

curl "https://havo.tj/api/v1/news/rss.xml?locale=tg"

Открыть в браузере → →

Ответы

200application/rss+xmlRSS 2.0

География

GET/api/v1/regionsкэш 600 s

Административные границы: области

Области, Душанбе и РРП с упрощёнными полигонами, центроидами, числом станций и худшим текущим уровнем индекса (0 — нет данных). Кэш 10 минут, ETag.

Пример запроса

curl "https://havo.tj/api/v1/regions"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

type "FeatureCollection"обяз.
features object[]обяз.
- type "Feature"обяз.
- id integerобяз.
- geometry objectобяз.
  - type "MultiPolygon"обяз.
  - coordinates any[]обяз.
- properties objectобяз.
  - id integerобяз.
  - code stringобяз.
  - name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
  - stationsCount integerобяз. — Public stations located inside the unit
  - level integerобяз. — Worst current index level among the unit's stations; 0 — no data or stale
  - sortOrder integerобяз.
  - centroid [number, number] | nullобяз.

GET/api/v1/districtsкэш 600 s

Административные границы: районы

Районы и города областного подчинения с упрощёнными полигонами, кодом области, числом станций и худшим текущим уровнем индекса. Единицы без загруженной геометрии не включаются.

Пример запроса

curl "https://havo.tj/api/v1/districts"

Открыть в браузере → →

Ответы

200application/jsonУспешный ответ

type "FeatureCollection"обяз.
features object[]обяз.
- type "Feature"обяз.
- id integerобяз.
- geometry objectобяз.
  - type "MultiPolygon"обяз.
  - coordinates any[]обяз.
- properties objectобяз.
  - id integerобяз.
  - code stringобяз.
  - name objectобяз. — Localized text: Tajik (tg), Russian (ru), English (en)
    tg string
    ru string
    en string
  - stationsCount integerобяз. — Public stations located inside the unit
  - level integerобяз. — Worst current index level among the unit's stations; 0 — no data or stale
  - regionId integerобяз. — Parent region id
  - regionCode stringобяз. — Parent region code (DU, RRP, SU, KT, GB)

Приём данных станций

POST/api/v1/ingest/{code}

Приём измерений от станции

Логгер, агент станции или вендорское ПО отправляют JSON‑массив измерений (до 1000 за запрос). Время — ISO 8601 с зоной или местное (Asia/Dushanbe); вещества — коды PM25, PM10, NO2, SO2, CO, O3 или синонимы; единица по умолчанию — единица ввода станции. Значения приводятся к единице вещества, проходят правило диапазона QC и записываются по ключу время/вещество/осреднение — повторная отправка идемпотентна, решения оператора сохраняются. Ответ содержит число принятых и отклонённых записей и причины по каждой. После записи пересчитывается индекс и правила уведомлений.

Параметры
Параметр	Где	Тип	Описание
`code`обяз.	path	string	Код станции из реестра (например DU-01)

Авторизация: Ключ API станции из карточки станции в панели администратора; передаётся заголовком Authorization: Bearer <ключ>. В базе хранится только хэш ключа.

Тело запроса

application/json

object[] | object

Пример запроса

curl -X POST "https://havo.tj/api/v1/ingest/DU-01" \
  -H "Authorization: Bearer <station-api-key>" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "time": "2026-10-18T07:00:00Z",
    "pollutant": "PM25",
    "value": 42.5
  },
  {
    "time": "2026-10-18 12:00",
    "pollutant": "pm2.5",
    "value": "12,5",
    "unit": "µg/m³"
  },
  {
    "time": "2026-10-18T07:00:00Z",
    "pollutant": "NO2",
    "value": 10,
    "unit": "ppb",
    "flag": "valid"
  },
  {
    "time": "2026-10-18T07:00:00Z",
    "pollutant": "CO",
    "value": null,
    "flag": "missing"
  }
]'

Ответы

200application/jsonПринята хотя бы одна запись (причины отклонённых — в errors)

station objectобяз.
- id integerобяз.
- code stringобяз.
- slug stringобяз.
received integerобяз. — Records in the request
accepted integerобяз. — Records stored (distinct time/pollutant/averaging keys)
rejected integerобяз. — Records rejected; see errors
inserted integerобяз. — New rows
updated integerобяз. — Existing rows overwritten (idempotent re-sends)
skippedLocked integerобяз. — Rows kept as decided by an operator (qc_locked)
invalidRange integerобяз. — Accepted values outside the QC range, stored with flag invalid
duplicates integerобяз. — Records superseded by a later record with the same key
from string (date-time) | nullобяз.
to string (date-time) | nullобяз.
pollutants string[]обяз. — Pollutant codes of accepted records
errors object[]обяз. — Per-record reasons for rejected and superseded records
- index integerобяз. — Index of the record in the request array
- message stringобяз. — Reason: time, futureTime, tooOld, unknownPollutant:X, pollutantNotConfigured:X, emptyValue, value:X, unit:X, unitConversion:X, averagingMin:X, duplicate

400application/jsonНекорректные параметры

error stringобяз. — unauthorized | station_inactive | invalid_json | validation | payload_too_large | rate_limited
message string
issues object[]
- path stringобяз.
- message stringобяз.

401application/jsonНет заголовка Authorization или ключ не подходит к коду станции

error stringобяз. — unauthorized | station_inactive | invalid_json | validation | payload_too_large | rate_limited
message string
issues object[]
- path stringобяз.
- message stringобяз.

403application/jsonСтанция приостановлена или выведена из эксплуатации

error stringобяз. — unauthorized | station_inactive | invalid_json | validation | payload_too_large | rate_limited
message string
issues object[]
- path stringобяз.
- message stringобяз.

413application/jsonТело больше 2 МБ

error stringобяз. — unauthorized | station_inactive | invalid_json | validation | payload_too_large | rate_limited
message string
issues object[]
- path stringобяз.
- message stringобяз.

422application/jsonНи одна запись не принята — см. errors

station objectобяз.
- id integerобяз.
- code stringобяз.
- slug stringобяз.
received integerобяз. — Records in the request
accepted integerобяз. — Records stored (distinct time/pollutant/averaging keys)
rejected integerобяз. — Records rejected; see errors
inserted integerобяз. — New rows
updated integerобяз. — Existing rows overwritten (idempotent re-sends)
skippedLocked integerобяз. — Rows kept as decided by an operator (qc_locked)
invalidRange integerобяз. — Accepted values outside the QC range, stored with flag invalid
duplicates integerобяз. — Records superseded by a later record with the same key
from string (date-time) | nullобяз.
to string (date-time) | nullобяз.
pollutants string[]обяз. — Pollutant codes of accepted records
errors object[]обяз. — Per-record reasons for rejected and superseded records
- index integerобяз. — Index of the record in the request array
- message stringобяз. — Reason: time, futureTime, tooOld, unknownPollutant:X, pollutantNotConfigured:X, emptyValue, value:X, unit:X, unitConversion:X, averagingMin:X, duplicate

429application/jsonПревышен лимит запросов станции (см. Retry-After)

error stringобяз. — unauthorized | station_inactive | invalid_json | validation | payload_too_large | rate_limited
message string
issues object[]
- path stringобяз.
- message stringобяз.

Данные — по лицензии CC BY 4.0 с указанием источника; прогнозы FMI — с указанием Финского метеорологического института.

Для сайтов без разработки есть iframe‑виджеты /embed/aqi, /embed/forecast и /embed/alerts (см. «Открытые данные»).