Introduction

Gundi's API is designed to enable data providers to transmit data intended for various supported platforms (e.g., EarthRanger, SMART, Movebank, and wpsWatch).

Base URL

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

Response Format

All responses are in JSON format.

Versioning

This documentation is for version v2 of the API.

Rate Limits

Gundi can process high volumes of data without enforcing a rate limit. However, destination systems (such as EarthRanger) may have difficulty handling data when it is sent at a fixed rate of around one location per second per device. In such cases, Gundi automatically retries, but we recommend reaching out to the Gundi team if you expect to send data at this frequency.

Authentication

All endpoints require an API key sent in the Authorization header:

apikey: API_KEY

This key can be obtained from your Connection created in the Gundi Portal. Check our documentation to create a new Connection, or request the API Key from our Support Team. Requests that do not include a key, or include an invalid or expired key, will be denied with an appropriate error response. 

Integration Overview

POST /events/

Events can be used for reports, alerts, incidents, or any event that requires awareness or action.

Required Headers

Query Parameters

Request Body

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

Example

{
   "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"
      ]
   }
}

Response

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}} 
}

PATCH /events/{object_id}/

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

Required Headers

Example

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

PATCH /events/{object_id}/attachments/

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

Required Headers

Example Request

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}}'

POST /observations/

Observations can be used to track wildlife, rangers, and assets.

Required Headers

Query Parameters

Request Body

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

Example

{
   "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
   }
}

Try it in Postman

Explore Postman Collection 

Last update: Aug 3, 2025