Air Raid Alert API (Ukraine, UNOFFICIAL)

(English version is available here.)

Цей API дозволяє вам отримувати інформацію про повітряні тривоги в Україні в режимі реального часу.

Наше джерело даних - Telegram-канал @air_alert_ua.

Події в середньому затримуются до 2-х секунд.

Зараз надаємо інформацію лише про області (24 області та м. Київ). Крим відсутній зі списку, оскільки по ньому відсутня інформація. Але ми всі знаємо, що Крим - це Україна.

Сервіс працює в двох режимах: HTTP та TCP.

За посиланням доступна статична карта: https://alerts.com.ua/map.png

Також ви можете отримувати історію всіх тривог у вигляді time series дампу (див. секцію A2).

Зверніть увагу, що цей сервіс не є офіційним. Ми залишаємо за собою право не нести відповідальність за збої в нашій системі.

Ви маєте право використовувати наше API в будь-яких цілях, зокрема в комерційних. Єдиний вийняток - це застосування нашого API для ведення підривної діяльності проти України, що є суворо забороненим. Такі дії будуть повідомлені в СБУ.

Наші проєкти

https://alerts.com.ua - ви зараз тут.
Спшенгло💥 - хочете допомогти фінансово або просто підпискою? Долучайтесь!

A. Режим HTTP

A1. Автентифікація

Вам потрібно ключ для роботи з цим API.

Щоб отримати ключ, надішліть мені e-mail (a@dun.ai) або повідомлення в Telegram (@andunai). Щоб прискорити отримання ключа, допишіть в текст свого повідомлення хештег “#api”.
Надсилайте ключ в кожному запиті в заголовку X-API-Key.
Для фронт-ендерів: вам знадобиться polyfill для EventStream, оскільки API EventStream в браузерах не підтримує надсилання заголовків в запиті.

Зверніть увагу, що це API має обмеження по частоті запитів:

Максимальна частота запитів з одної адреси: 10/сек
Максимальна частота запитів по одному API-ключу: 100/сек
Максимальна частота запитів до ендпоїнту /api/history: 1/хв

Якщо ви перевищите зазначені ліміти, ви отримаєте HTTP 429.

A2. Ендпоїнти

`GET /api/states`

Повертає список областей з їхніми статусами.

# $ curl https://alerts.com.ua/api/states -H "X-API-Key: yourApiKey34421337"

{
  "states": [
    {
      "id": 1,
      "name": "Вінницька область",
      "name_en": "Vinnytsia oblast",
      "alert": false,
      "changed": "2022-04-05T06:12:52+03:00"
    },
    {
      "id": 2,
      "name": "Волинська область",
      "name_en": "Volyn oblast",
      "alert": false,
      "changed": "2022-04-05T06:13:06+03:00"
    },
    # ...
  ],
  "last_update": "2022-04-05T06:15:10.333210918+03:00"
}

Для економії трафіку можна додати ?short до URL запиту, щоб отримувати лише поля id та alert.

`GET /api/states/<ID>`

Повертає область та статус тривоги за її ID.

# $ curl https://alerts.com.ua/api/states/12 -H "X-API-Key: yourApiKey34421337"

{
  "state": {
    "id": 12,
    "name": "Львівська область",
    "name_en": "Lviv oblast",
    "alert": false,
    "changed": "2022-04-05T06:13:12+03:00"
  },
  "last_update": "2022-04-05T06:15:10.333210918+03:00"
}

`GET /api/states/live` & `GET /api/states/live/<ID>`

SSE-ендпоінт, який генерує події в режимі реального часу.

Якщо передати параметр ID, то ви будете отримувати лише події, пов’язані з цією областю.

Приклад клієнта: https://codesandbox.io/s/goofy-elgamal-mkdkzv?file=/src/App.js

# $ curl https://alerts.com.ua/api/states/live -H "X-API-Key: yourApiKey34421337"

event: hello
data: null

event: ping
data: null

event: ping
data: null

event: update
data: {"state":{"id":12,"name":"Львівська область","name_en":"Lviv oblast","alert":false,"changed":"2022-04-05T06:14:56+03:00"},"notification_id":"b7b5cb85-ddc0-11ec-90d3-c8b29b63332d"}

event: ping
data: null

# ...

`GET /api/history`

Повертає історію всіх тривог.

Цей ендпоїнт можна викликати лише 1 раз на хвилину.

# $ curl https://alerts.com.ua/api/history -H "X-API-Key: yourApiKey34421337"

[
  {"id":1,"date":"2022-03-15T18:02:56+02:00","state_id":9,"alert":false},
  {"id":2,"date":"2022-03-15T18:10:34+02:00","state_id":1,"alert":true},
  {"id":3,"date":"2022-03-15T18:11:25+02:00","state_id":5,"alert":true},
  {"id":4,"date":"2022-03-15T18:15:11+02:00","state_id":10,"alert":true},
  {"id":5,"date":"2022-03-15T18:17:28+02:00","state_id":8,"alert":true},
  {"id":6,"date":"2022-03-15T18:17:29+02:00","state_id":12,"alert":true},
  {"id":7,"date":"2022-03-15T18:18:35+02:00","state_id":16,"alert":true},
  {"id":8,"date":"2022-03-15T18:19:13+02:00","state_id":2,"alert":true},
  {"id":9,"date":"2022-03-15T18:19:20+02:00","state_id":25,"alert":true},
  {"id":10,"date":"2022-03-15T18:22:29+02:00","state_id":18,"alert":true},
  {"id":11,"date":"2022-03-15T18:30:17+02:00","state_id":24,"alert":true},
  # ...
]

B. Режим TCP

Якщо ви хочете використати наше API в інтегрованих системах - наприклад, Arduino чи ESP8266, то вам буде значно простіше та економніше отримувати сповіщення через старі добрі TCP-сокети.

TCP-сервер працює за адресою tcp.alerts.com.ua на порті 1024.

Приклад проекту для ESP8266: https://wokwi.com/projects/330842127136195154

B1. Структура пакетів

Всі повідомлення від сервера мають наступний формат:

ТипПакета:Дані\n

Кожен пакет, що надсилається серверу та отримується від нього, повинен завершуватись ASCII-символом 0x10 (\n).

Тип пакета	Опис функції	Опис даних
`a`	auth-пакет, містить результат авторизації	`ok`, `timeout` або `wrong_api_key`
`p`	ping-пакет, надсилається сервером кожні 15 секунд	Випадкове число в діапазоні [0;10000)
`s`	state-пакет, містить інформацію про зміну статусу тривоги в деякій області	Номер області та статус тривоги. Наприклад, при активації тривоги в Львівській області міститиме текст `12=1`

B2. Протокол спілкування з TCP-сервером

Клієнт під’єднується і впродовж 3 секунд надсилає свій API-ключ в ASCII-кодуванні:
```
yourApiKey34421337
```
Це - єдиний пакет, який клієнт надсилає серверові.

Ви також можете повідомити сервер, що бажаєте отримувати статуси лише для однієї області. Для цього додайте через кому номер області після ключа, наприклад:
```
yourApiKey34421337,12
```
Сервер надсилає auth-пакет, який містить відповідь з інформацією про успішність авторизації:
```
a:ok
```
В разі невдалої авторизації або тайм-ауту замість ok буде тип помилки (див. попередню секцію).
Сервер надсилає по одному state-пакету зі станами тривог в кожній області.
Сервер періодично надсилає ping-пакети (кожні 15 секунд).
В разі зміни статусу тривоги в області, сервер надсилає state-пакет.

Приклад TCP-сесії (префікс > означає дані, надіслані клієнтом, < - дані, надіслані сервером, а # - коментарі):

> yourApiKey34421337     # Клієнт надіслав API-ключ
< a:ok                   # Авторизація успішна
< s:1=0                  # Початкові дані про 25 областей
< s:2=0
< s:3=0
...                      # (пропущено 20 рядків)
< s:24=0
< s:25=0
< p:1241                 # Пінг-пакет
< p:2508                 # ...
< p:1902
< p:9028
< s:12=1                 # У Львівській області тривога!
< p:3819
< p:9873
< s:12=0                 # Відбій тривоги у Львівській області
< p:8321                 # Пінг-пакет
< p:3985                 # ...

Use the source, Luke

Цю штуку зробив Andrew Dunai.

Початковий код знаходиться тут: https://github.com/and3rson/raid

Але навіщо?

Я є прихильником відкритих даних та вільного програмного забезпечення.

Я вважаю, що будь-яку інформацію, яка є відкритою, будь-хто повинен мати змогу опрацьовувати так, як йому заманеться, якщо тільки це не приносить комусь шкоди.

“Але ж… Хіба ”безкоштовний” і ”вільний” - не те саме?”

“Безкоштовний” (“gratis”) не є синонімом для “вільний” (“libre”).

Для прикладу, Інстаграм - безкоштовний, але він не є вільний: вони змушують вас використовувати саме їх власний додаток і не дають повного контролю над своїми даними та доступом до них. Точніше, дають, але дуже обмежений доступ. Це і означає термін “невільний” в контексті комп’ютерних технологій.

Не ставайте рабами постачальників.

Давайте зробимо світ вільнішим.

*stallman.jpg*