Gundi's API

Pushing Data through Gundi

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

I. Authentication

This API uses API key-based authentication. To authenticate, you must obtain an API key from the Connection created through the Gundi Portal, or 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. 

Make sure to keep your API key secure and do not share it publicly, as it provides access to potentially sensitive data and operations.

Include your key in your API calls as a header.

Content-Type: application/json  
apikey: {{API_KEY}}

II. Events

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

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

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

How to make an API call

Endpoint
 
POST https://sensors.api.gundiservice.org/v2/events/

Headers

Content-Type: application/json  
apikey: {{API_KEY}}

Body (JSON)

{
 	"source": "{{SOURCE_ID}}",
 	"title": "{{EVENT_TITLE}}",
 	"event_type": "{{EVENT_TYPE}}",
 	"recorded_at": "{{TIMESTAMP}}",
 	"location": {
   		"lat": {{LATITUDE}},
   		"lon": {{LONGITUDE}}
 	},
 	"event_details": {
 	}
}
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

Example of API call

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

Example of API 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}} 
}

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.

Example of API call

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.

Example of API call

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

Example of API response

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

III. Observations

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

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

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

How to make an API call

Endpoint
 
POST https://sensors.api.gundiservice.org/v2/observations/

Headers

Content-Type: application/json  
apikey: {{API_KEY}}

Body (JSON)

{
 	"source": "{{SOURCE_ID}}",
 	"subject_type": "{{SUBJECT_TYPE}}",
 	"source_name": "{{SOURCE_NAME}}",
 	"recorded_at": "{{TIMESTAMP}}",
 	"location": {
   		"lat": {{LATITUDE}},
   		"lon": {{LONGITUDE}}
 	},
 	"additional": {
 	}
}
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

Example of API call

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