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
You can make up to one request per minute.
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
Header | Value | Description |
---|---|---|
apikey |
{{API_KEY}} |
Your API key for authentication |
Content-Type |
application/json |
Specifies the media type of the body |
Query Parameters
Attributes | ||
source |
Identifies a unique device associated with the event. | optional |
title |
A human-friendly string as the event's title. Appears in EarthRanger's event feed and map view. | required |
event_type |
Represents the appropriate EarthRanger Event Type or SMART category corresponding to the report. | required |
recorded_at |
A timestamp including a timezone, recommended in ISO format (e.g., 2023-07-27T09:34-03:00 or 2023-07-27T09:34Z). | required |
location |
A dictionary with lon (longitude) and lat (latitude) to indicate the event's location. The lon and lat values are decimal degrees in WGS-84. | required |
event_details |
A dictionary of event properties matching the schema for the associated "event type" (in EarthRanger) or category (in SMART Connect). | optional |
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
Header | Value | Description |
---|---|---|
apikey |
{{API_KEY}} |
Your API key for authentication |
Content-Type |
application/json |
Specifies the media type of the body |
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
Header | Value | Description |
---|---|---|
apikey |
{{API_KEY}} |
Your API key for authentication |
Content-Type |
application/json |
Specifies the media type of the body |
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
Header | Value | Description |
---|---|---|
apikey |
{{API_KEY}} |
Your API key for authentication |
Content-Type |
application/json |
Specifies the media type of the body |
Query Parameters
Attributes | ||
source |
A unique identifier for the device reporting its position. | required |
source_name |
A human-friendly name for the device. If omitted, the source identifier will be used as the default. | optional |
subject_type |
Describes the entity being tracked (e.g., 'ranger', 'elephant', 'helicopter'). In EarthRanger, this corresponds to the subject’s sub-type. | optional |
recorded_at |
The timestamp of when the position was recorded, including a timezone. Use ISO format (e.g., 2022-01-10T16:43:32Z) for consistency. | required |
location |
A dictionary containing the track-point coordinates: lon (longitude) and lat (latitude) in decimal degrees (WGS-84). | required |
additional |
A dictionary for custom key-value pairs specific to the tracked device, allowing storage of extra metadata beyond standard fields. | optional |
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
Last update: Aug 3, 2025