API développeur

Bientôt

Une API REST pour la foudre en direct et historique autour de vos lieux. Ci-dessous le contrat prévu ; le service en production arrive avec le backend.

URL de base:https://api.zappollo.appv1

Tous les endpoints sont sous /v1. Les changements incompatibles arrivent en nouvelle version avec une période de dépréciation.

Authentification

Passez votre clé API en jeton bearer :

Authorization: Bearer zpk_live_…

Démarrage rapide

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"

Endpoints

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).

Réponse exemple

{
  "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
}

Concepts clés

Erreurs

problem+json cohérent (RFC 7807) avec type, status et request_id.

Pagination

Par curseur — passez "next" de la réponse en ?cursor.

Limites de débit

Quotas par clé ; voir les en-têtes X-RateLimit-*.

Idempotence

Envoyez un en-tête Idempotency-Key sur les écritures pour des reprises sûres.

Erreurs · 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"
}

Webhooks

Abonnez une géozone et recevez des POST signés. Vérifiez le HMAC X-Zappollo-Signature.

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 et outils

SDK officiels JavaScript/TypeScript et Python, une collection Postman et une spec OpenAPI 3.

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

Vous construisez quelque chose ? Obtenez une clé API pour votre événement ou plateforme.

Demander un accès API

Zapollo · OpenStreetMap · OpenWeather · Blitzortung.org