Meldefuchs
Meldefuchs.de

API-Dokumentation

v1

REST-API für Entwickler, Kommunen und Fachstellen – Meldungen, Statistiken und Geodaten programmatisch nutzen.

Einstieg

Die Meldefuchs-API folgt REST-Konventionen. Alle Antworten sind JSON mit UTF-8-Kodierung. Die Basis-URL lautet: 

https://meldefuchs.de/api/v1

Ein einfacher Verbindungstest:

GET https://meldefuchs.de/api/v1

Die API kann im ACP aktiviert oder deaktiviert werden. Einzelne Features (z. B. Statistik, Geocoding) lassen sich dort separat steuern.

Authentifizierung

Je nach Konfiguration sind Lese- und Schreibzugriffe mit einem API-Schlüssel geschützt. Schlüssel werden im ACP erstellt und mit Berechtigungen (read, write, admin) versehen.

Header-Varianten

X-API-Key: mf_…
Authorization: Bearer mf_…

Schreibzugriff (POST /reports) erfordert in der Regel einen Key mit Scope write. Bearbeiten und Löschen (PATCH, DELETE) benötigen admin.

Antwortformat

Erfolgreiche Antworten:

{
  "success": true,
  "message": "OK",
  "api_version": "1.0",
  "data": { … }
}

Paginierte Listen (GET /reports) enthalten zusätzlich meta:

{
  "success": true,
  "data": [ … ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 128,
    "total_pages": 3
  }
}

Fehlerantworten:

{
  "success": false,
  "message": "Beschreibung des Fehlers",
  "api_version": "1.0"
}

Typische HTTP-Statuscodes: 400 (Validierung), 401 (Key fehlt), 403 (Feature/Scope), 404, 422, 503 (Wartung/API aus).

Endpoints

GET /config

Öffentliche App-Konfiguration: Kategorien, Nestgrößen, Karten-Defaults, API-Flags.

GET /reports

Meldungen auflisten (paginiert).

Query-Parameter

  • category – z. B. eichenprozessionsspinner
  • page, per_page – Pagination (max. 100 pro Seite)
  • bounds – Kartenausschnitt als lat_min,lng_min,lat_max,lng_max
GET /reports/{id}

Einzelne Meldung abrufen.

POST /reports

Neue Meldung anlegen (JSON-Body).

Pflichtfelder

  • latitude, longitude

Optional

  • category (Standard: eichenprozessionsspinner)
  • nest_size – klein, mittel, gross, unbekannt
  • description, reporter_name, reporter_email
PATCH /reports/{id}

Meldung bearbeiten (Status, Nestgröße, Beschreibung, Koordinaten). Erfordert Admin-Scope.

DELETE /reports/{id}

Meldung löschen. Erfordert Admin-Scope.

GET /stats

Aggregierte Statistik: Gesamtzahl, Bezirke, Nestgrößen, Zeitreihen, Heatmap-Punkte.

Parameter: category (optional)

GET /geocode

Reverse-Geocoding für Koordinaten → Bezirk/Straße.

Parameter: lat, lng

Beispiele

Meldungen abrufen

curl -s "https://meldefuchs.de/api/v1/reports?per_page=10" \
  -H "X-API-Key: mf_IHR_SCHLUESSEL"

Meldung erstellen

curl -s -X POST "https://meldefuchs.de/api/v1/reports" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mf_IHR_SCHLUESSEL" \
  -d '{
    "category": "eichenprozessionsspinner",
    "latitude": 52.520008,
    "longitude": 13.404954,
    "nest_size": "mittel",
    "description": "Nest an Eiche im Park"
  }'

Statistik

curl -s "https://meldefuchs.de/api/v1/stats" \
  -H "X-API-Key: mf_IHR_SCHLUESSEL"

Hinweise

  • CORS: Kann im ACP für Browser-Apps freigeschaltet werden.
  • Rate-Limit: Aktiv – standardmäßig 120 Anfragen pro Minute und IP (konfigurierbar im ACP). Bei Überschreitung: HTTP 429 mit Retry-After.
  • Wartungsmodus: Neue Meldungen per API werden während der Wartung blockiert (HTTP 503).
  • Legacy-API: https://meldefuchs.de/api/reports bleibt für die Website bestehen; neue Integrationen sollten v1 nutzen.
← Zur Startseite