Audience

Data Providers who want to transmit data for conservation purposes to any of the Gundi supported platforms  (e.g., EarthRanger, SMART Connect, Movebank, and wpsWatch).

Authentication

To authenticate with the Gundi API, include your API key in the request header. Each client is provided a unique API key.

Events

Posting Events

Use the events endpoint to share event information. Events can be used for reports, alerts, incidents, or any event that requires awareness or action.

The following table outlines the essential properties within an event payload.

The following example demonstrates the use of the /events/ endpoint.

curl --location 'https://sensors.api.gundiservice.org/v2/events/' \
--header 'Content-Type: application/json' \
--header 'apikey: {{API_KEY}}' \
--data '{
   "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"
       ]
   }
}'
'

If the operation is successful, our API v2 will provide you with an Object ID, which can be utilized later for various updates and use cases. Make sure to note down this {{OBJECT_ID}} if you anticipate needing the additional functionality.

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

Updating Events

To update an event previously sent to Gundi's API, use the PATCH method and include only the properties you want to modify.

The following example illustrates updating an event's location, status, and an additional property. Replace the {{OBJECT_ID}} placeholder with the unique ID obtained from the event creation response. For more details on how to obtain this ID, refer to the previous section.

curl --location --request PATCH 'https://sensors.api.gundiservice.org/v2/events/{{OBJECT_ID}}/' \
--header 'apikey: {{API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
   "status" : "resolved",
   "location":{
       "lat":13.527,
       "lon":13.154
   },
   "event_details":{
       "number_people_involved":"3"
   }
}'

Posting an Image

Camera trap images can be attached to events using the attachments endpoint.

This example illustrates the process of updating an event with an image through Gundi's API. Pay attention to the {{OBJECT_ID}} placeholder in the endpoint, which should be substituted with the value obtained from the event creation operation's result (refer to the "Posting Events").

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

If the operation is successful, our API will provide you with an Object ID, which can be utilized later for various updates and use cases. Make sure to note down this Object ID if you anticipate needing the additional functionality.

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

Observations

Posting Observations 

Movement data can be posted using the observations endpoint.  Observations can be used to track wildlife, rangers, and assets.

The following table outlines the essential properties within a Position payload.

The following example demonstrates the use of the  /observations/ endpoint.

curl --location 'https://sensors.api.gundiservice.org/v2/observations/' \
--header 'Content-Type: application/json' \
--header 'apikey: {{API_KEY}}' \
--data '{
   "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
   }
}'

Audience

Developers interested in receiving data from physical or virtual sensors supported by Gundi for conservation efforts.