Alerts UKR · APIКарта тривог

API повітряних тривог

Безкоштовний JSON API з поточними тривогами по містах, громадах, районах і областях України та якістю повітря. Один ключ на користувача, до 10 запитів на хвилину.

Ваш ключ

Щоб отримати ключ, увійдіть через Telegram. Ключ видається один на акаунт Telegram. Якщо ключ уже створено, ви побачите той самий.

Тримайте ключ у себе й не публікуйте його. Ліміт 10 запитів на хвилину діє на ключ. Для більшого навантаження кешуйте відповіді: дані оновлюються приблизно раз на 15 секунд.

Доступ і ліміти

Базова адреса: https://alerts.31.77.13.165.nip.io

Передайте ключ одним із способів:

Усі запити — GET, відповіді — application/json; charset=utf-8, CORS дозволено. Ліміт — 10 запитів на хвилину на ключ. Заголовки відповіді:

ЗаголовокЗначення
X-RateLimit-Limit10
X-RateLimit-Remainingскільки запитів лишилось у поточній хвилині
Retry-Afterсекунд до наступного дозволеного запиту (лише при коді 429)

GET /v1/alerts

Усі активні тривоги в Україні.

ПараметрОпис
oblastобласть або її початок, наприклад Дніпропетровська
typeoblast, raion, hromada або city
alert_typeair_raid, artillery_shelling, urban_fights, chemical, nuclear
qчастина назви місця
curl -H "X-API-Key: ВАШ_КЛЮЧ" "BASE/v1/alerts?oblast=Дніпропетровська&type=city"
{
  "updated_at": "2026-10-03T08:20:11.000Z",
  "age_seconds": 7,
  "stale": false,
  "count": 1,
  "source": "alerts.in.ua",
  "alerts": [
    {
      "id": 1234,
      "location_title": "м. Дніпро",
      "location_type": "city",
      "location_oblast": "Дніпропетровська область",
      "alert_type": "air_raid",
      "started_at": "2026-10-03T08:11:00.000Z",
      "threats": [ { "threat_type": "drones", "started_at": "2026-10-03T08:12:00.000Z" } ]
    }
  ]
}

stale: true означає, що дані старші за 2 хвилини: показуйте користувачеві попередження. Можливі threat_type: drones, ballistic_missiles, cruise_missiles, unspecified_missiles, guided_aerial_bombs, mig31k_departure, tactic_aircraft_activity, strategic_aircraft_activity.

GET /v1/alerts/place

Чи є зараз повітряна тривога в конкретному місті. Збігається лише назва самого міста (з українськими закінченнями), область не рахується.

ПараметрОпис
nameназва міста, мінімум 3 символи (обов’язково)
curl -H "X-API-Key: ВАШ_КЛЮЧ" "BASE/v1/alerts/place?name=Кам’янське"
{ "place": "Кам’янське", "active": false, "age_seconds": 9, "stale": false, "source": "alerts.in.ua", "alerts": [] }

GET /v1/threats

Рух цілей за повідомленнями Telegram-каналів (БпЛА, ракети, КАБи, авіація, МіГ-31К). Сервер сам розбирає пости каналів. Позиції орієнтовні, це не дані радара: точки й напрямки взяті з тексту повідомлень.

ПараметрОпис
typedrone, jet_drone, missile, mig31k, kab, aircraft
sourceid каналу, наприклад kpszsu
curl -H "X-API-Key: ВАШ_КЛЮЧ" "BASE/v1/threats?type=drone"
{
  "updated_at": "2026-10-03T09:10:00.000Z",
  "count": 1,
  "note": "Орієнтовні позиції за повідомленнями Telegram-каналів, це не дані радара",
  "sources": [ { "id": "kpszsu", "name": "Повітряні Сили ЗСУ", "ok": true, "age_seconds": 12 } ],
  "threats": [
    {
      "type": "drone",
      "time": "2026-10-03T09:04:00.000Z",
      "age_minutes": 6,
      "source": "monitor1654",
      "text": "Знов фіксується курсом на Дніпропетровщину",
      "global": false,
      "region": "Дніпропетровська область",
      "position": null,
      "from": null,
      "to": { "lat": 48.46, "lon": 35.04 },
      "heading_deg": null,
      "approximate": true
    }
  ]
}

global: true означає загальне повідомлення без місця (наприклад, вильот МіГ-31К). heading_deg — курс у градусах (0 = північ), якщо відомі точки from і to. Свіжість цілей: БпЛА 25 хв, ракети 15, КАБи 20, авіація 30, МіГ-31К 40.

GET /v1/air

Якість повітря: медіана PM2.5 за станціями SaveEcoBot у радіусі, дані не старші за 3 години.

ПараметрЗа замовчуваннямОпис
lat, lon48.51, 34.60координати точки
radius_km12радіус пошуку станцій, до 50
curl -H "X-API-Key: ВАШ_КЛЮЧ" "BASE/v1/air?lat=48.46&lon=35.04&radius_km=15"
{ "lat": 48.46, "lon": 35.04, "radius_km": 15, "age_seconds": 120, "source": "SaveEcoBot",
  "stations": 6, "pm25": 11.4, "aqi": 52, "level": "green" }

level: green (AQI до 100), pink (до 150), purple (до 200), dark (вище). Якщо свіжих станцій немає, pm25, aqi і level дорівнюють null.

GET /v1/status

Вік даних на сервері. Також витрачає один запит із ліміту.

{ "ok": true, "alerts_age_seconds": 6, "air_age_seconds": 92, "source": "alerts.in.ua, SaveEcoBot" }

Приклади коду

JavaScript

const r = await fetch("BASE/v1/alerts/place?name=Дніпро", { headers: { "X-API-Key": "ВАШ_КЛЮЧ" } });
const data = await r.json();
if (data.active) console.log("Тривога!", data.alerts);

Python

import requests
r = requests.get("BASE/v1/alerts", params={"oblast": "Харківська"}, headers={"X-API-Key": "ВАШ_КЛЮЧ"}, timeout=15)
r.raise_for_status()
print(r.json()["count"])

Помилки

КодЗначення
400bad_request: некоректні параметри
401unauthorized: ключ відсутній або невірний
429rate_limited: більше 10 запитів на хвилину, див. Retry-After
503unavailable: дані ще завантажуються або джерело недоступне
{ "error": "rate_limited", "message": "Ліміт: 10 запитів на хвилину", "retry_after": 23 }

Джерела й умови