開発者 API

近日公開

拠点周辺のライブ・履歴落雷のための REST API。以下は予定している仕様で、本番提供はバックエンドと共に開始します。

ベース URL:https://api.zappollo.appv1

すべてのエンドポイントは /v1 配下。互換性のない変更は廃止予定期間つきの新バージョンとして提供します。

認証

API キーを bearer トークンとして渡します:

Authorization: Bearer zpk_live_…

クイックスタート

curl -H "Authorization: Bearer zpk_live_…" \
  "https://api.zappollo.app/v1/lightning?lat=48.2&lon=11.6&radius_km=50&since=2026-06-03T13:00:00Z"

エンドポイント

Lightning core
GET/v1/lightning?bbox={w,s,e,n}&since={iso}&limit=1000

Recent strikes in a bounding box.

GET/v1/lightning?lat={lat}&lon={lon}&radius_km=50&since={iso}

Recent strikes within a radius.

POST/v1/lightning/query

Query by GeoJSON polygon, type (CG/IC), polarity and min peak current (kA).

GET/v1/lightning/history?lat=&lon=&radius_km=&from=&to=

Historical strikes for a point, radius and time range.

GET/v1/lightning/{id}

Full detail: kA, polarity, error ellipse, stations, confidence.

GET/v1/lightning/density?bbox=&cell=h3:7&since=

Gridded strike counts (H3/geohash) for heatmaps.

Nowcasting & storm cells
GET/v1/cells?bbox=

Active storm cells with centroid, intensity, heading and speed.

GET/v1/cells/{id}/forecast?minutes=60

0–60 min nowcast track + ETA to a point.

GET/v1/risk?lat=&lon=

Combined storm-risk score (lightning + precipitation + wind).

Real-time & safety
WSwss://stream.zappollo.app/v1/lightning?bbox=

Live strike stream over WebSocket.

GET/v1/stream/sse?bbox=

Live strike stream over Server-Sent Events.

POST/v1/alerts/subscribe

Geofence webhook subscription (signed deliveries).

GET/v1/safety?lat=&lon=&radius_km=13

Safety status: watch / warning / all-clear (30-30 rule).

Maps & tiles
GET/v1/tiles/density/{z}/{x}/{y}.png

Raster density tiles.

GET/v1/tiles/strikes/{z}/{x}/{y}.mvt

Vector tiles (MVT) of strikes and cells.

GET/v1/static?lat=&lon=&zoom=&w=800&h=600

Static map PNG snapshot (embeddable in reports).

Weather context
GET/v1/weather?lat=&lon=

Current conditions + short-term precipitation nowcast.

Reports & compliance
POST/v1/reports/verify

Was there a strike within R km of a point between T1–T2? Returns JSON + signed PDF.

GET/v1/reports/{id}

Fetch a generated report or strike certificate.

Analytics & bulk
GET/v1/stats?region=DE-BY&from=&to=&interval=hour

Aggregated counts and trends.

GET/v1/export?from=&to=&format=ndjson

Bulk export (enterprise).

レスポンス例

{
  "data": [
    {
      "id": "a1b2c3",
      "t": "2026-06-03T14:02:11.482Z",
      "lat": 48.214, "lon": 11.553,
      "type": "CG", "polarity": "-", "peak_kA": 14.2,
      "ellipse_km": 0.4, "stations": 9, "confidence": 0.97,
      "source": "certified-net"
    }
  ],
  "next": "c2Vfb2Zmc2V0PTEwMDA",
  "count": 1
}

基本コンセプト

エラー

type・status・request_id を持つ一貫した problem+json（RFC 7807）。

ページネーション

カーソル方式 — レスポンスの "next" を ?cursor として渡します。

レート制限

キーごとのクォータ。X-RateLimit-* レスポンスヘッダーを参照。

冪等性

書き込み時に Idempotency-Key ヘッダーを送ると再試行が安全になります。

エラー · problem+json
{
  "type": "https://docs.zappollo.app/errors/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "60 req/min exceeded. Retry after 12s.",
  "request_id": "req_8f2a91c4"
}

Webhook

ジオフェンスを購読し、署名付き POST を受信。X-Zappollo-Signature の HMAC を検証します。

POST https://your-app.com/hooks/zappollo
X-Zappollo-Signature: t=1717423331,v1=5e1b…

{ "event": "strike.near", "place_id": "venue-12",
  "strike": { "id": "a1b2c3", "distance_km": 7, "t": "…" } }

SDK とツール

公式の JavaScript/TypeScript・Python SDK、Postman コレクション、OpenAPI 3 仕様。

@zappollo/sdk (JS/TS)zappollo (Python)Postman collectionopenapi.yaml

何か作っていますか？イベントやプラットフォーム用の API キーを取得しましょう。

API アクセスを申請

Zapollo · OpenStreetMap · OpenWeather · Blitzortung.org