{"openapi":"3.0.3","info":{"title":"AlarmMap API","version":"1.0.0","description":"Адміністративний поділ, геометрія територій, надзвичайні ситуації, повідомлення та оновлення SSE. Країну задає параметр country; доступність адміністративних даних залежить від країни."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/monitoring/emergencies":{"get":{"summary":"Зміни надзвичайних ситуацій SSE","description":"Потребує API-ключа. Лише нові зміни та heartbeat кожні 10 секунд. Без початкового знімка та відтворення Last-Event-ID. Відкриття враховується у квоті HTTP-запитів.","responses":{"200":{"description":"Іменовані SSE-події з JSON у data.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"event: heartbeat\nid: 1\ndata: {\"ts\":1790146800000}\n\n"}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}},"x-sse-events":{"heartbeat":{"schema":{"type":"object","required":["ts"],"properties":{"ts":{"type":"integer","format":"int64"}}}},"emergency":{"description":"Оголошення або зміна рівня: katottg, type, level, start. Завершення: katottg, type, end.","schema":{"oneOf":[{"type":"object","required":["katottg","type","level","start"],"properties":{"katottg":{"type":"string"},"type":{"type":"string"},"level":{"type":"integer"},"start":{"type":"string","format":"date-time"}}},{"type":"object","required":["katottg","type","end"],"properties":{"katottg":{"type":"string"},"type":{"type":"string"},"end":{"type":"string","format":"date-time"}}}]}}}}},"/monitoring/events":{"get":{"summary":"Нові повідомлення SSE","description":"Потребує API-ключа. Лише нові зміни та heartbeat кожні 10 секунд. Без початкового знімка та відтворення Last-Event-ID. Відкриття враховується у квоті HTTP-запитів.","responses":{"200":{"description":"Іменовані SSE-події з JSON у data.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"event: heartbeat\nid: 1\ndata: {\"ts\":1790146800000}\n\n"}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}},"x-sse-events":{"heartbeat":{"schema":{"type":"object","required":["ts"],"properties":{"ts":{"type":"integer","format":"int64"}}}},"event":{"description":"Нове опубліковане повідомлення або публікація чернетки. Дата в UTC.","schema":{"type":"object","required":["title","text","type","date","katottgs"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","description":"Категорія повідомлення."},"date":{"type":"string","format":"date-time"},"katottgs":{"type":"array","items":{"type":"string"},"description":"Коди територій або global для загального повідомлення."}}}}}}},"/event/types":{"get":{"summary":"Типи повідомлень","responses":{"200":{"description":"Типи повідомлень.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","title"],"properties":{"slug":{"type":"string"},"title":{"type":"string"}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/event/type/{type}":{"get":{"summary":"Повідомлення за типом","description":"До десяти останніх опублікованих повідомлень указаного типу.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["drone","rocket","ballistics","airplane","tactical","artillery"]}}],"responses":{"200":{"description":"Опубліковані повідомлення.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":10,"items":{"type":"object","required":["title","text","type","date","katottgs"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","description":"Категорія повідомлення."},"date":{"type":"string","format":"date-time"},"katottgs":{"type":"array","items":{"type":"string"},"description":"Коди територій або global для загального повідомлення."}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"422":{"description":"Некоректний параметр URL."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/event/territory/{katottg}":{"get":{"summary":"Повідомлення території","description":"До десяти останніх опублікованих повідомлень із точним збігом у katottgs. global та ієрархія територій автоматично не включаються.","parameters":[{"name":"katottg","in":"path","required":true,"schema":{"type":"string","pattern":"^UA[0-9]{17}$"}}],"responses":{"200":{"description":"Опубліковані повідомлення.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":10,"items":{"type":"object","required":["title","text","type","date","katottgs"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","description":"Категорія повідомлення."},"date":{"type":"string","format":"date-time"},"katottgs":{"type":"array","items":{"type":"string"},"description":"Коди територій або global для загального повідомлення."}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"422":{"description":"Некоректний параметр URL."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/event/time/{timestamp}":{"get":{"summary":"Повідомлення на вказаний час","description":"До десяти останніх опублікованих повідомлень із date <= timestamp. Unix timestamp у мілісекундах; дати відповіді у UTC.","parameters":[{"name":"timestamp","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":8640000000000000,"example":1790146800000}}],"responses":{"200":{"description":"Опубліковані повідомлення.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":10,"items":{"type":"object","required":["title","text","type","date","katottgs"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","description":"Категорія повідомлення."},"date":{"type":"string","format":"date-time"},"katottgs":{"type":"array","items":{"type":"string"},"description":"Коди територій або global для загального повідомлення."}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"422":{"description":"Некоректний параметр URL."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/event":{"get":{"summary":"Повідомлення","description":"До десяти останніх опублікованих повідомлень, від новіших до старіших. Потребує API-ключа.","responses":{"200":{"description":"Опубліковані повідомлення.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":10,"items":{"type":"object","required":["title","text","type","date","katottgs"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","description":"Категорія повідомлення."},"date":{"type":"string","format":"date-time"},"katottgs":{"type":"array","items":{"type":"string"},"description":"Коди територій або global для загального повідомлення."}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/emergencies":{"get":{"summary":"Поточні надзвичайні ситуації","description":"Усі поточні ситуації без відбору за країною або територією. Масив без обгортки data. Потребує API-ключа. Затримка оновлення відповіді до 15 секунд.","responses":{"200":{"description":"Масив активних ситуацій; порожній масив, якщо записів немає.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["katottg","type","level","start","end"],"properties":{"katottg":{"type":"string"},"type":{"type":"string"},"level":{"type":"integer"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","nullable":true,"enum":[null]}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/emergencies/types":{"get":{"summary":"Типи надзвичайних ситуацій","description":"Довідник типів надзвичайних ситуацій. Потребує API-ключа. slug відповідає полю type у ситуаціях і рівнях.","responses":{"200":{"description":"Типи ситуацій.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","title"],"properties":{"slug":{"type":"string"},"title":{"type":"string"}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/emergencies/levels":{"get":{"summary":"Рівні надзвичайних ситуацій","description":"Назви й описи рівнів для всіх типів ситуацій. Сортування за type, потім level. Потребує API-ключа.","responses":{"200":{"description":"Довідник рівнів.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["type","level","title","description"],"properties":{"type":{"type":"string"},"level":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/emergencies/{country}":{"get":{"summary":"Надзвичайні ситуації країни","description":"Поточні ситуації всіх адміністративних рівнів. Потребує API-ключа. Затримка оновлення відповіді до 15 секунд.","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}}],"responses":{"200":{"description":"Поточні ситуації країни.","content":{"application/json":{"schema":{"type":"object","required":["country","data"],"properties":{"country":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["katottg","type","level","start","end"],"properties":{"katottg":{"type":"string"},"type":{"type":"string"},"level":{"type":"integer"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","nullable":true,"enum":[null]}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/emergencies/{country}/{katottg}":{"get":{"summary":"Надзвичайні ситуації території","description":"Поточні ситуації території та її батьківських одиниць. Ситуації дочірніх територій не включаються. Потребує API-ключа.","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}},{"name":"katottg","in":"path","required":true,"schema":{"type":"string","pattern":"^UA[0-9]{17}$"}}],"responses":{"200":{"description":"Поточні ситуації території.","content":{"application/json":{"schema":{"type":"object","required":["country","katottg","data"],"properties":{"country":{"type":"string"},"katottg":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["katottg","type","level","start","end"],"properties":{"katottg":{"type":"string"},"type":{"type":"string"},"level":{"type":"integer"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","nullable":true,"enum":[null]}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/geo/{country}":{"get":{"summary":"Геометрія територій","description":"Межі адміністративних одиниць верхнього рівня. Потребує API-ключа. Координати GeoJSON: довгота, широта, WGS 84.","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}}],"responses":{"200":{"description":"Колекція GeoJSON. Для території без геометрії geometry дорівнює null.","content":{"application/geo+json":{"schema":{"type":"object","required":["type","features"],"properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","required":["type","properties","geometry"],"properties":{"type":{"type":"string","enum":["Feature"]},"properties":{"type":"object","required":["country","katottg","full_name"],"properties":{"country":{"type":"string"},"katottg":{"type":"string"},"full_name":{"type":"string","nullable":true}}},"geometry":{"type":"object","nullable":true,"required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"]},"coordinates":{"oneOf":[{"type":"array","minItems":1,"items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"},"description":"Довгота, широта у градусах WGS 84."}}},{"type":"array","minItems":1,"items":{"type":"array","minItems":1,"items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"},"description":"Довгота, широта у градусах WGS 84."}}}}]}}}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/geo/{country}/{katottg}":{"get":{"summary":"Геометрія території","description":"Об’єкт GeoJSON однієї території. Потребує API-ключа.","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}},{"name":"katottg","in":"path","required":true,"schema":{"type":"string","pattern":"^UA[0-9]{17}$"}}],"responses":{"200":{"description":"Об’єкт Feature. Для території без геометрії geometry дорівнює null.","content":{"application/geo+json":{"schema":{"type":"object","required":["type","properties","geometry"],"properties":{"type":{"type":"string","enum":["Feature"]},"properties":{"type":"object","required":["country","katottg","full_name"],"properties":{"country":{"type":"string"},"katottg":{"type":"string"},"full_name":{"type":"string","nullable":true}}},"geometry":{"type":"object","nullable":true,"required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"]},"coordinates":{"oneOf":[{"type":"array","minItems":1,"items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"},"description":"Довгота, широта у градусах WGS 84."}}},{"type":"array","minItems":1,"items":{"type":"array","minItems":1,"items":{"type":"array","minItems":4,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"},"description":"Довгота, широта у градусах WGS 84."}}}}]}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/atu":{"get":{"summary":"Країни","description":"Повертає масив кодів ISO 3166-1 alpha-2 та українських назв країн, відсортований за кодом. Параметри та тіло запиту не потрібні. Потребує API-ключа.","responses":{"200":{"description":"Країни з довідника ATU.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","pattern":"^[a-z]{2}$"},"name":{"type":"string"}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/atu/{country}":{"get":{"summary":"Список територій","description":"Повертає верхній рівень адміністративного поділу країни. Потребує API-ключа.","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}}],"responses":{"200":{"description":"Список адміністративних одиниць.","content":{"application/json":{"schema":{"type":"object","required":["country","data"],"properties":{"country":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"},"data":{"type":"array","items":{"type":"object","required":["name","full_name","slug","katottg"],"properties":{"name":{"type":"string"},"full_name":{"type":"string"},"slug":{"type":"string"},"katottg":{"type":"string","pattern":"^UA[0-9]{17}$"},"parent_katottg":{"type":"string","nullable":true},"category":{"type":"string"},"level":{"type":"integer"}}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/atu/{country}/{katottg}":{"get":{"summary":"Територія","parameters":[{"name":"country","in":"path","required":true,"description":"Дволітерний код ISO 3166-1 alpha-2 у нижньому регістрі зі списку /api/v1/atu.","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"}},{"name":"katottg","in":"path","required":true,"schema":{"type":"string","pattern":"^UA[0-9]{17}$"}}],"responses":{"200":{"description":"Адміністративна одиниця.","content":{"application/json":{"schema":{"type":"object","required":["country","data"],"properties":{"country":{"type":"string","pattern":"^[a-z]{2}$","example":"ua"},"data":{"type":"object","required":["name","full_name","slug","katottg"],"properties":{"name":{"type":"string"},"full_name":{"type":"string"},"slug":{"type":"string"},"katottg":{"type":"string","pattern":"^UA[0-9]{17}$"},"parent_katottg":{"type":"string","nullable":true},"category":{"type":"string"},"level":{"type":"integer"}}}}}}}},"401":{"description":"Потрібен чинний API-ключ підтвердженого облікового запису."},"404":{"description":"Країну або територію не знайдено."},"409":{"description":"Адміністративні дані країни ще не доступні."},"422":{"description":"Неправильний формат коду країни або території."},"429":{"description":"Квоту вичерпано. Час очікування наведений у Retry-After."}}}},"/check":{"get":{"summary":"Перевірка доступу до API","description":"Потребує API-ключа. Не змінює дані. Запит враховується у спільній квоті облікового запису: 5 запитів за секунду та 10 000 за добу.","responses":{"200":{"description":"Доступ підтверджено.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","enum":[true]}}},"example":{"ok":true}}}},"401":{"description":"API-ключ відсутній, недійсний або відкликаний; пошта облікового запису має бути підтверджена."},"429":{"description":"Квоту вичерпано. Повторіть запит через кількість секунд із Retry-After."}}}}}}