API de Gundi

Introduction

L'API de Gundi est conçue pour permettre aux fournisseurs de données de transmettre des données destinées à diverses plates-formes prises en charge (par exemple, EarthRanger , SMART, Movebank et wpsWatch).

URL de base

https://sensors.api.gundiservice.org/v2/

Format de réponse

Toutes les réponses sont au format JSON.

Gestion des versions

Cette documentation concerne la version v2 de l'API.

Limites de taux

Gundi peut traiter de gros volumes de données sans limite de débit. Cependant, les systèmes de destination (comme EarthRanger ) peuvent rencontrer des difficultés à gérer les données lorsqu'elles sont envoyées à un débit fixe d'environ un emplacement par seconde et par appareil. Dans ce cas, Gundi réessaie automatiquement, mais nous vous recommandons de contacter l'équipe Gundi si vous prévoyez d'envoyer des données à cette fréquence.

Authentification

Tous les points de terminaison nécessitent une clé API envoyée dans l'en-tête Authorization :

apikey: API_KEY

Cette clé peut être obtenue à partir de votre connexion créée sur le portail Gundi . Consultez notre documentation pour créer une nouvelle connexion ou demandez la clé API à notre équipe d'assistance. Les demandes sans clé, invalides ou expirées seront refusées et afficheront une erreur.

Veuillez conserver votre clé API en sécurité et ne la partagez pas publiquement, car elle donne accès à des données et opérations sensibles.

Présentation de l'intégration


POST /events/

Les événements peuvent être utilisés pour des rapports, des alertes, des incidents ou tout événement nécessitant une sensibilisation ou une action.

En-têtes obligatoires

En-tête Valeur Description
apikey {{API_KEY}} Votre clé API pour l'authentification
Content-Type application/json Spécifie le type de support du corps

Paramètres de requête

Attributs
source Identifie un appareil unique associé à l'événement.

facultatif

title Une chaîne de caractères conviviale comme titre de l'événement. Apparaît dans le flux d'événements et la vue cartographique d' EarthRanger .

requis

event_type Représente le type d'événement EarthRanger approprié ou la catégorie SMART correspondant au rapport.

requis

recorded_at Un horodatage incluant un fuseau horaire, recommandé au format ISO (par exemple, 2023-07-27T09:34-03:00 ou 2023-07-27T09:34Z).

requis

location Un dictionnaire avec les coordonnées lon (longitude) et lat (latitude) pour indiquer le lieu de l'événement. Les valeurs lon et lat sont exprimées en degrés décimaux selon le système WGS-84.

requis

event_details Un dictionnaire de propriétés d'événement correspondant au schéma du « type d'événement » associé (dans EarthRanger ) ou de la catégorie (dans SMART Connect).

facultatif

Corps de la requête

{
 	"source": "{{SOURCE_ID}}",
 	"title": "{{EVENT_TITLE}}",
 	"event_type": "{{EVENT_TYPE}}",
 	"recorded_at": "{{TIMESTAMP}}",
 	"location": {
   		"lat": {{LATITUDE}},
   		"lon": {{LONGITUDE}}
 	},
 	"event_details": {
 	}
}

Exemple

{
   "source":"none",
   "title":"Accident Report",
   "event_type":"accident_rep",
   "recorded_at":"2023-10-03T09:35Z",
   "location":{
      "lat":20.117625,
      "lon":-103.113061
   },
   "event_details":{
      "area":"1",
      "people_affected":"1",
      "tags":[
         "fall",
         "injury"
      ]
   }
}

Réponse

Si l'opération réussit, notre API v2 vous fournira un identifiant d'objet, utilisable ultérieurement pour diverses mises à jour et cas d'utilisation. N'oubliez pas de noter cet {{OBJECT_ID}} si vous prévoyez d'avoir besoin de cette fonctionnalité supplémentaire.

200 OK
{ 
  "object_id": {{OBJECT_ID}}, 
  "created_at": {{CREATED_AT}} 
}


PATCH /events/{object_id}/

Pour mettre à jour un événement précédemment envoyé à l'API de Gundi, utilisez la méthode PATCH et incluez uniquement les propriétés que vous souhaitez modifier.

En-têtes obligatoires

En-tête Valeur Description
apikey {{API_KEY}} Votre clé API pour l'authentification
Content-Type application/json Spécifie le type de support du corps

Exemple

{
   "status":"resolved",
   "location":{
      "lat":13.527,
      "lon":13.154
   },
   "event_details":{
      "number_people_involved":"3"
   }
}


PATCH /events/{object_id}/attachments/

Les images de pièges photographiques peuvent être jointes aux événements à l'aide du point de terminaison des pièces jointes.

En-têtes obligatoires

En-tête Valeur Description
apikey {{API_KEY}} Votre clé API pour l'authentification
Content-Type application/json Spécifie le type de support du corps

Exemple de demande

Cet exemple illustre le processus de mise à jour d'un événement avec une image via l'API Gundi. Attention à l'espace réservé {{OBJECT_ID}} dans le point de terminaison, qui doit être remplacé par la valeur obtenue à partir du résultat de la création de l'événement (voir « Publication d'événements »).

curl --location 'https://sensors.api.gundiservice.org/v2/events/{{OBJECT_ID}}/attachments/' \
--header 'apikey: {{API_KEY}}' \
--form 'file1={{Blob}}'


POST /observations/

Les observations peuvent être utilisées pour suivre la faune, les gardes forestiers et les biens.

En-têtes obligatoires

En-tête Valeur Description
apikey {{API_KEY}} Votre clé API pour l'authentification
Content-Type application/json Spécifie le type de support du corps

Paramètres de requête

Attributs
source Un identifiant unique pour l'appareil signalant sa position.

requis

source_name Nom convivial pour l'appareil. S'il est omis, l'identifiant source sera utilisé par défaut.

facultatif

subject_type Décrit l'entité suivie (par exemple, « ranger », « éléphant », « hélicoptère »). Dans EarthRanger , cela correspond au sous-type du sujet.

facultatif

recorded_at Horodatage de l'enregistrement de la position, incluant le fuseau horaire. Utilisez le format ISO (par exemple, 2022-01-10T16:43:32Z) pour plus de cohérence.

requis

location Un dictionnaire contenant les coordonnées des points de suivi : lon (longitude) et lat (latitude) en degrés décimaux (WGS-84).

requis

additional

Un dictionnaire pour les paires clé-valeur personnalisées spécifiques à l'appareil suivi, permettant le stockage de métadonnées supplémentaires au-delà des champs standard.

Ce champ peut recevoir n'importe quel JSON valide.

facultatif

Corps de la requête

{
 	"source": "{{SOURCE_ID}}",
 	"subject_type": "{{SUBJECT_TYPE}}",
 	"source_name": "{{SOURCE_NAME}}",
 	"recorded_at": "{{TIMESTAMP}}",
 	"location": {
   		"lat": {{LATITUDE}},
   		"lon": {{LONGITUDE}}
 	},
 	"additional": {
 	}
}

Exemple

{
   "source":"ST123456789",
   "subject_type":"cow",
   "source_name":"Buttercup",
   "recorded_at":"2023-10-04T00:44:32Z",
   "location":{
      "lat":-51.769228,
      "lon":-72.004443
   },
   "additional":{
      "speed_kmph":3
   }
}

 

Essayez-le dans Postman

Découvrez la collection Postman

 

Dernière mise à jour : 3 août 2025