开发者 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
}

核心概念

错误

一致的 problem+json（RFC 7807），含 type、status 和 request_id。

分页

基于游标 — 将响应中的 "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