Built by and for the global conservation community, Gundi (a word meaning "glue" in Swahili), is a free and open-source data integration platform that seamlessly connects any sensor and any application.
There are a growing number of different types of hardware and software available at the fingertips of conservationists. But most of these technologies are developed independently and often need to talk better with one another. As a result, time could be more spent building custom integrations or workarounds.
Whether you're a developer or conservationist in the field, Gundi connects your data and technologies so you can spend your limited time and resources doing what you do best.
On this wiki page we describe and explain all aspects of Gundi relevant to the Smart Parks stack. For more details on all other aspects of Gundi we'd like to refer to their own documentation on their Gundi project website.
Within the Smart Parks Stack the integration to EcoScope needs to be properly configured to offer the wide variety of features.
Gundi's API is designed to enable data providers to transmit data intended for various supported platforms (e.g., EarthRanger, SMART, Movebank, and wpsWatch).
As an API client, you will authenticate using an API Key.
For each connection, our team will supply you with a unique API Key. It is important to note that the keys do not expire, and we encourage you to keep them safe. If you require an additional API Key or have any inquiries, please reach out to us at info@projectgundi.org.
Include your API Key as an HTTP header in your requests.
apikey: YOUR_API_KEY
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.
| Attribute | Description |
Required |
source |
This identifies a unique device associated with the event. | yes |
title |
A human-friendly string as the event's title. This will appear in EarthRanger's event feed and map view. | yes |
event_type |
This value represents the appropriate EarthRanger Event Type or SMART category that corresponds to the report. | yes |
recorded_at |
A timestamp which should include a timezone. We recommend using ISO format (ex. 2023-07-27T09:34-03:00 or 2023-07-27T09:34Z ). |
yes |
location |
A dictionary including lon (longitude), lat (latitude), and alt (altitude) to indicate the event's location. The lon and lat values are decimal degrees in WGS-84. |
yes |
|
|
A dictionary of event properties. The keys and values in this dictionary must match the schema for the associated "event type" (in EarthRanger) or category (in SMART Connect). |
no |
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: {{YOUR_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}}
}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 previous section for more details).
curl --location
'https://sensors.api.gundiservice.org/v2/events/{{OBJECT_ID}}/attachments/' \
--header 'apikey: {{YOUR_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}}
}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.
| Attribute | Description |
Required |
source |
A unique identifier for the device reporting its position. | yes |
source_name |
An optional friendly name for the device. If not provided, the device_id will be used. | no |
|
|
The type of thing being tracked. If the data is destined for EarthRanger, this maps to a subject's sub-type. (Ex. 'ranger', 'elephant', 'helicopter') | no |
recorded_at |
A timestamp which should include a timezone. We recommend using ISO format (ex. 2022-01-10 09:43:32-0700 or 2022- 01-10T16:43:32Z ) |
yes |
location |
A dictionary representing the track-point location. Values for lon (longitude) and lat (latitude) are decimal degrees in WGS-84. |
yes |
additional |
A dictionary of custom properties associated with the Position. This dictionary can contain any key-value pairs and is a good place for data that is specific to the tracked device but does not fit into the standard fields. | no |
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: {{YOUR_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
}
}'