Kommunikation¶

Über den Menüpunkt Kommunikation verlassen Informationen den Vogelschlagmelder. Für jede neue Meldung kann eine Nachricht per E-Mail oder in einen Matrix-Chat gehen. Außerdem werden hier API-Schlüssel erzeugt, mit denen eigene Programme oder Webseiten die Daten abrufen.

E-Mail-Benachrichtigungen¶

Empfänger¶

Jede eingetragene Adresse erhält bei jeder neuen Meldung eine E-Mail mit dem Betreff „Neue Vogelschlag-Meldung“. Mit + kommt ein weiteres Feld hinzu, × entfernt eine Adresse. Speichern übernimmt die ganze Liste.

Statt mehrerer einzelner Adressen eignet sich auch ein Verteiler der Gruppe. Eine Bestätigung an die meldende Person verschickt der Vogelschlagmelder nicht.

Mailserver (SMTP)¶

Damit E-Mails verschickt werden können, braucht der Vogelschlagmelder die Zugangsdaten eines Mailservers – zum Beispiel eines eigenen Postfachs beim Webhoster der Gruppe. Diese Daten werden in der Regel bei der Installation in der .env eingetragen.

In der Adminoberfläche erscheinen sie zunächst nur zur Ansicht. Bearbeiten lassen sie sich hier nur, wenn in der .env die Variable ALLOW_SMTP_OVERRIDE=true gesetzt ist. Die in der Adminoberfläche eingetragenen Werte haben dann Vorrang vor der .env.

Feld	Inhalt
SMTP_HOST	Adresse des Mailservers, z. B. `smtp.example.org`
SMTP_PORT	meist `587` (STARTTLS) oder `465` (SSL)
SMTP_USER, SMTP_PASSWORD	Zugangsdaten des Postfachs
SMTP_FROM	Absenderadresse
SMTP_STARTTLS	`true` für Port 587
FROM_EMAIL	überschreibt die Absenderadresse, falls sie vom Benutzernamen abweicht
FROM_NAME	Anzeigename des Absenders, z. B. „Vogelschlagmelder Jena“

Ein gespeichertes Passwort erscheint als ********. Bleibt das so stehen, ändert sich das Passwort nicht; wird das Feld geleert, wird es gelöscht.

Kein Testversand

Eine Schaltfläche für eine Test-E-Mail gibt es nicht. Ob der Versand funktioniert, zeigt am einfachsten eine Testmeldung über das Meldeformular, die anschließend in der Meldezentrale gelöscht wird. Schlägt der Versand fehl, steht der Grund im Protokoll des Containers (siehe Wartung).

Element/Matrix Chat-Integration¶

Benachrichtigungen lassen sich auch in einen Chatraum auf einem Matrix-Server schicken, etwa im NABU-Chat. Dafür werden die Adresse des Servers (Homeserver-URL) und ein Access-Token eines Chat-Kontos benötigt.

Einstellungen der Matrix-Benachrichtigungen in der Adminoberfläche

Im Folgenden wird beschrieben, wie der Access-Token für den NABU-Chat (chat.nabu-netz.de) erzeugt wird. Da der NABU-Chat auf Element läuft, gilt die Anleitung auch für andere Element-Server.

Eigenes Chat-Konto für den Melder

Die Nachrichten erscheinen im Namen des Kontos, dessen Token eingetragen ist. Besser als ein persönliches Konto ist ein eigenes Konto, etwa „Vogelschlagmelder Jena“. Dann bleibt die Benachrichtigung auch bestehen, wenn die einrichtende Person die Gruppe verlässt.

Im NABU-Chat anmelden und die Einstellungen öffnen (Zahnradsymbol unten links), dann Alle Einstellungen wählen.

Links Hilfe & Info wählen und nach unten bis Erweitert scrollen. Dort auf Zugriffstoken klicken.

Zugriffstoken in den Einstellungen des Element-Chats

Den Access-Token kopieren und in der Adminoberfläche zusammen mit der Homeserver URL (für den NABU-Chat https://chat.nabu-netz.de) eintragen. Zugangsdaten speichern übernimmt beide.
Einen Chatraum für die Meldungen anlegen und das Chat-Konto des Melders einladen. Alle Personen, die die Meldungen erhalten sollen, treten diesem Raum bei.
Im Bereich Chatraum auswählen unter Anderen Raum suchen den Namen des Raums eingeben und Suchen klicken. Angezeigt werden nur Räume, in denen das Chat-Konto bereits Mitglied ist. Auswählen verbindet den Raum und schaltet die Benachrichtigung ein.
Test senden schickt eine Testnachricht in den Raum.

Access-Token wie ein Passwort behandeln

Mit dem Access-Token kann jeder im Namen des Chat-Kontos Nachrichten lesen und schreiben. Er darf nicht weitergegeben werden. Wer den Token in Element abmeldet oder das Passwort des Kontos ändert, macht ihn ungültig; dann muss ein neuer Token eingetragen werden.

Mit Deaktivieren werden die Matrix-Nachrichten pausiert, ohne die Einstellungen zu verlieren; Aktivieren schaltet sie wieder ein. Werden Homeserver oder Token neu gespeichert, ist danach der Raum erneut auszuwählen.

Die Homeserver-URL muss mit https:// beginnen.

Inhalt der Benachrichtigungen¶

Auswahl der Inhalte für E-Mail- und Matrix-Benachrichtigungen

Hier wird festgelegt, welche Angaben einer Meldung in E-Mail und Matrix-Nachricht stehen. In der Voreinstellung ist alles ausgewählt:

Zeitpunkt, Standort (Koordinaten), Adresse und Hinweise zum Ort
Vogelfund, Vogelart, Scheibenabdruck, Abdruckgröße und Ausrichtung der Fassade
Name, E-Mail und Telefon der meldenden Person
Bilder – als Liste der Dateinamen, nicht als Anhang
Link zur Meldung in der Meldezentrale

Die Nummer der Meldung und die Überschrift stehen immer in der Nachricht.

Datensparsam benachrichtigen

Landet die Benachrichtigung in einem größeren Chatraum oder Verteiler, sollten die Kontaktdaten abgewählt werden. Über den Link zur Meldezentrale sind sie für alle mit Zugang weiterhin erreichbar.

Der Link zur Meldezentrale wird aus der Variable PUBLIC_BASE_URL in der .env gebildet. Zeigt er auf eine falsche Adresse, ist dort der Fehler zu suchen.

API-Key¶

Der Vogelschlagmelder bietet eine Schnittstelle (API), über die eigene Programme oder Webseiten Meldungen und Statistiken abrufen. Für die geschützten Daten ist ein API-Schlüssel nötig.

Unter Name des Schlüssels wird eine Bezeichnung eingetragen, etwa „Webseite NABU Jena“, dann Erstellen. Der Schlüssel erscheint nur einmal und muss sofort kopiert werden: Der Vogelschlagmelder speichert nur einen Hash des Schlüssels und kann ihn später nicht mehr anzeigen. Geht ein Schlüssel verloren, wird er gelöscht und ein neuer erstellt. Für jede Anwendung sollte ein eigener Schlüssel angelegt werden; wird er nicht mehr gebraucht, entfernt ihn Löschen.

Der Schlüssel öffnet Kontaktdaten

Die geschützten Endpunkte liefern die Meldungen samt E-Mail-Adresse und Telefonnummer der Meldenden. Ein API-Schlüssel gehört deshalb nicht in den Quelltext einer öffentlichen Webseite, sondern nur auf einen Server, der die Daten weiterverarbeitet.

Aufruf¶

Der Schlüssel wird im Header X-API-Key mitgeschickt. Bei der Beschreibung der Endpunkte steht {{baseUrl}} für die Adresse des Vogelschlagmelders, z. B. https://vogelschlag.example.org.

curl -H "X-API-Key: <SCHLÜSSEL>" {{baseUrl}}/api/v1/statistik

Alle Zeitangaben sind deutsche Ortszeit ohne Zeitzonenkennung. Der Zeitpunkt einer Meldung (timestamp) ist der Zeitpunkt, der im Meldeformular eingetragen wurde; „heute“, „diese Woche“ usw. beginnen um 0:00 Uhr Ortszeit, die Woche am Montag. generated_at ist der Zeitpunkt, zu dem die Antwort erstellt wurde.

Geschützte Endpunkte¶

Endpunkt	Inhalt
`GET /api/v1/meldungen/heute`	alle Meldungen seit 0:00 Uhr, die neueste zuerst
`GET /api/v1/meldungen/letzte`	die zuletzt eingegangene Meldung
`GET /api/v1/statistik`	Kennzahlen und Auswertungen

/api/v1/meldungen/heute

{
  "count": 2,
  "collision_total": 3,
  "reports": [ { "id": 17, "...": "..." } ]
}

count ist die Zahl der Meldungen, collision_total die Summe der Kollisionen. Duplikate sind enthalten und an "duplicate": true erkennbar.

/api/v1/meldungen/letzte liefert {"report": { … }} oder {"report": null}, wenn es noch keine Meldung gibt.

Eine einzelne Meldung sieht so aus:

{
  "id": 17,
  "lat": 50.929502,
  "lng": 11.582336,
  "timestamp": "2026-10-02T10:21:00",
  "bird_status": "Tot",
  "has_window_imprint": true,
  "window_imprint": "ja",
  "bird_found": "tot",
  "bird_species": "Rotkehlchen",
  "imprint_size": "10–20 cm",
  "collision_count": 2,
  "facade_orientation": "Süden",
  "location_hint": "Glasfassade Hörsaalgebäude, Seite zum Platz",
  "email": "anna.mueller@example.org",
  "phone": null,
  "image_paths": ["/uploads/2026-10-02-08-21_id17_72e21363.jpg"],
  "duplicate": false,
  "duplicate_reference_id": null,
  "is_verified": false
}

window_imprint gibt den Scheibenabdruck als ja, nein oder unbekannt an. has_window_imprint ist nur bei ja wahr und bleibt für bestehende Auswertungen erhalten.

Die Bildpfade lassen sich nicht mit dem API-Schlüssel abrufen, sondern nur mit einer Anmeldung in der Meldezentrale.

/api/v1/statistik

{
  "summary": {
    "total": 23, "report_count": 16, "today": 2,
    "this_week": 2, "this_month": 2, "this_year": 23
  },
  "by_year": { "2026": 23 },
  "by_status": { "Tot": 9, "Scheibenabdruck": 10, "Lebendig": 4 },
  "by_orientation": { "Süden": 7, "Südwesten": 6, "Osten": 3, "…": 1 },
  "by_month_current_year": { "1": 0, "2": 0, "3": 4, "4": 2, "…": 0 },
  "generated_at": "2026-10-02T10:31:35.208714"
}

Alle Werte zählen Kollisionen ohne Duplikate. report_count ist die Zahl der Meldungen ohne Duplikate. by_status verwendet dieselben Werte wie die Spalte „Vogelzustand“ im CSV-Export. In total sind die historischen Daten enthalten, wenn sie für die Gesamtstatistik eingeschaltet sind (siehe Historische Daten).

Ein ungültiger oder gelöschter Schlüssel wird mit dem Status 401 abgewiesen, ein fehlender Header mit 422.

Öffentliche Endpunkte¶

Zwei Endpunkte sind ohne Schlüssel abrufbar. Sie liefern keine personenbezogenen Daten.

Daten der Gefahrenkarte

{{baseUrl}}/api/heatmap-data

Beispielantwort:

{"grid_data":[{"bounds":[[50.91720979279279,11.576277332667376],[50.91901159459459,11.579135770045028]],"count":1},{"bounds":[[50.91540799099099,11.570560457912071],[50.9172097927928,11.573418895289723]],"count":2}],"thresholds":{"low":{"min":2,"color":"#ffeb3b"},"medium":{"min":15,"color":"#ff9800"},"high":{"min":25,"color":"#f44336"}},"grid_size_meters":200}

grid_data enthält je Rasterquadrat die Eckkoordinaten (Süd-West und Nord-Ost) und die Zahl der Kollisionen. thresholds und grid_size_meters entsprechen den Einstellungen der Gefahrenkarte.

Meldebereich

{{baseUrl}}/api/map-settings

Liefert Mittelpunkt, Zoomstufe, Radius und Modus des Meldebereichs sowie gegebenenfalls die Grenzen der Landkreise oder das Polygon als GeoJSON.

Handbuch Vogelschlagmelder

Navigation