How to get air-raid alert data programmatically

Three answers to the three questions a developer actually asks: how to start, how to stop polling, and where the history is.

The shortest path — one request, no key

No key, no sign-up. Without a key the limit is 60 requests per minute per address; with a free key it is 120.

curl -s https://map.megainet.art/api/alerts.php

In the response: regions — the state of 25 oblasts, updated — when it was taken, stale — whether the sources are silent (then the last known copy is returned). changed_ts says WHEN the state changed: that is what alert duration is counted from.

import json, urllib.request

with urllib.request.urlopen("https://map.megainet.art/api/alerts.php") as r:
    data = json.load(r)

for iso, region in data["regions"].items():
    if region["alert"]:
        print(iso, "— тривога")

How to stop polling: a webhook instead

Polling every 15 seconds is 5,760 requests a day for a dozen events. A subscription sends the event the moment it happens.

$ts   = $_SERVER['HTTP_X_MAP_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_MAP_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

// Перевіряємо підпис ДО того, як щось зробимо з подією.
if (!hash_equals(hash_hmac('sha256', $ts . "\n" . $body, $SECRET), $sig)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);   // alert.start | alert.end

Every delivery is signed: the headers are X-Map-Timestamp, X-Map-Signature (HMAC-SHA256 over «timestamp \n body»), X-Map-Event and X-Map-Delivery. Verify the signature BEFORE you act on the event: your receiver address will be discovered sooner or later, and without verification anyone can send you an “alert” in our name — and that alert may switch on a siren at your site.

No 2xx answer — we retry after 1, 5, 30 minutes, 2 and 6 hours. Answer 2xx IMMEDIATELY and do your work afterwards: we wait 8 seconds.

Where to get the per-oblast history

How many alerts there were in a day and how many hours an oblast spent under alert:

curl -s "https://map.megainet.art/api/history.php?hours=24"
curl -s "https://map.megainet.art/api/analytics.php?hours=168"

The period is 24, 48 or 168 hours. A limit worth knowing up front: targets are kept for 24 hours, the monitor feed for 72. A weekly analysis OF TARGETS does not exist physically, and no parameter will return it.

What it costs

The core is free forever. You pay only for a higher limit and for not having to show the credit link; webhooks are paid too.

A ready-made client

A dependency-free Python client (every method, webhook signature verification, a ready receiver) — ask for the link at [email protected]: the library is not published yet.

Full API reference Pricing Get a key