API publique SignalNids

Base & format de réponse

Toutes les URLs d’API partent de :

https://signalnids.fr

Les réponses sont encodées en JSON avec :

Content-Type: application/json; charset=utf-8

Par convention, un succès ressemble à :

{
  "ok": true,
  "items": [...]
}

Et une erreur à :

{
  "ok": false,
  "error": "Message lisible",
  "code": 422
}

Premier appel cURL

Exemple minimal pour récupérer les derniers signalements publics en JSON :

curl -s https://signalnids.fr/api/reports_latest.php

Vous pouvez ajouter un paramètre limit (par défaut 20, max 100) :

curl -s "https://signalnids.fr/api/reports_latest.php?limit=50"

Pour filtrer par zone géographique ou par commune, un endpoint spécifique pourra être ouvert sur demande (mairies, ruchers, associations).

GET Derniers signalements publics

GET https://signalnids.fr/api/reports_latest.php?limit=20

Public — renvoie les N derniers signalements visibles avec ville, coordonnées approximatives, intensité, statut et date.

{
  "ok": true,
  "items": [
    {
      "id": 123,
      "city": "Arras",
      "latitude": 50.289650,
      "longitude": 2.780573,
      "intensity": 3,
      "status": "a_verifier",
      "created_at": "2025-10-24 10:56:00"
    }
  ]
}

Les coordonnées sont volontairement décalées de quelques mètres pour préserver la vie privée.

POST Créer un signalement

POST https://signalnids.fr/api/report_create.php (auth + CSRF)

Corps de requête : multipart/form-data (recommandé, permet l’upload de photos) ou application/x-www-form-urlencoded.

Champs principaux :

• latitude, longitude, city
• intensity (1 à 5)
• species (ex. frelon_asiatique)
• nest_location (arbre, toiture, ruche…)
• status (souvent a_verifier à la création)
• comment (texte libre)
• photos[] (0 à N fichiers JPEG/PNG/WebP)

curl -X POST https://signalnids.fr/api/report_create.php \
  -H "X-CSRF-Token: <csrf>" \
  -F "latitude=50.28965" \
  -F "longitude=2.780573" \
  -F "city=Arras" \
  -F "intensity=3" \
  -F "species=frelon_asiatique" \
  -F "nest_location=arbre" \
  -F "status=a_verifier" \
  -F "comment=Nid sous la toiture" \
  -F "photos[]=@/chemin/photo1.jpg"

{"ok": true, "id": 456}

POST Voter (like / dislike)

POST https://signalnids.fr/api/report_vote.php (auth + CSRF)

Permet de voter pour un signalement (utile / peu utile). Champs : report_id, value ∈ {-1, 0, 1} où 0 annule le vote.

curl -X POST https://signalnids.fr/api/report_vote.php \
  -H "X-CSRF-Token: <csrf>" \
  -d "report_id=456" \
  -d "value=1"

{"ok": true, "likes": 3, "dislikes": 0, "user_vote": 1}

GET Notifications (auth)

GET https://signalnids.fr/api/notifications_list.php

Retourne les notifications récentes (likes, validations, etc.) pour l’utilisateur connecté.

{
  "ok": true,
  "items": [
    {
      "id": 12,
      "type": "like",
      "actor_name": "Alice",
      "actor_avatar": "/uploads/avatars/a.png",
      "report_id": 456,
      "report_city": "Arras",
      "link": "/signalement.php?id=456",
      "created_at": "2025-10-24 11:10:00",
      "read_at": null
    }
  ]
}

Pour marquer comme lues, utiliser POST https://signalnids.fr/api/notifications_read.php avec ids=all ou une liste d’identifiants.

Modes d’authentification

• Session + CSRF (navigateur) : l’utilisateur est connecté à SignalNids, le token CSRF est transmis via un champ csrf ou un header X-CSRF-Token.
• Bearer (script / serveur à serveur) : pour certains cas, un jeton d’accès dédié peut être fourni, à placer dans le header Authorization: Bearer <token>.

Les endpoints d’écriture refuseront les requêtes sans authentification correcte.

Sécurité & vie privée

• Connexion chiffrée uniquement (HTTPS).
• CSRF exigé sur tous les endpoints d’écriture en contexte session (création de nid, votes, etc.).
• Uploads restreints (JPEG / PNG / WebP) avec contrôle de taille et de mimetype.
• Coordonnées des nids affichées de façon approximative pour limiter les risques (domicile, rucher privé…).

Pagination & limites

La plupart des endpoints « liste » acceptent les paramètres :

• page (défaut : 1)
• limit (défaut : 20, max recommandé : 100)

GET https://signalnids.fr/api/reports_latest.php?page=2&limit=20

En cas d’abus, une réponse 429 Too Many Requests peut être renvoyée avec un message explicite dans error.

Gestion des erreurs

{"ok": false, "error": "Paramètres invalides", "code": 422}

Codes HTTP les plus courants :

• 400 — requête invalide (paramètre manquant ou mal formé)
• 401 — non authentifié
• 403 — CSRF invalide ou droits insuffisants
• 404 — ressource introuvable
• 422 — validation échouée (latitude/longitude incorrectes…)
• 429 — trop de requêtes
• 500 — erreur serveur

Exemples d’intégration

• Site de mairie : carte des nids signalés dans la commune, basée sur reports_latest.php filtré par zone.
• Rucher / syndicat apicole : tableau des signalements dans un rayon donné autour des ruchers.
• Outils internes : liste des nids à traiter, scripts de suivi, génération de rapports PDF, etc.

Tout usage public doit mentionner clairement la source SignalNids.

Versionning de l’API

L’API actuelle est une v1 sans préfixe dédié (les URLs sont directement sous /api/…).

En cas de rupture de compatibilité, une nouvelle version préfixée (/v2/...) sera annoncée à l’avance dans le Changelog et documentée ici.

Pour les besoins particuliers (exports massifs, agrégats par commune ou département), n’hésitez pas à nous contacter.