NAV
shell http

Introduction

Welcome to the Adiuvo API.

You can use this API to access your Adiuvo data.

You can view API calls examples in the dark area to the right. You can switch the language (currently shell or http) of the examples with the tabs in the top right.

This documentation refers to API version v0.4.1-alpha released on April 2023.

Authentication

Copy to Clipboard
curl "https://api.adiuvo.it" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "message": "Welcome to Adiuvo API v0.4.1-alpha",
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

Make sure to replace customer-api-key with your actual customer API key.

Adiuvo uses API keys to allow endpoints access.

Go to Adiuvo console to get your customer API key.

Adiuvo API expects for the API key to be included in all restricted API calls as a custom HTTP header:

X-Api-Key: customer-api-key

Devices (legacy calls)

Get available devices

Copy to Clipboard
curl "https://api.adiuvo.it/devices" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "devices": [
        {
            "alias": "Device alias",
            "clientChannel": "mqtt",
            "clientId": "AA428E915840A1681C11C923378FCEBA",
            "createMillis": 1632258739649,
            "lastConnectionMillis": 1666162928681,
            "lastEventMillis": 1666162928681,
            "topics": [
                "atmosphericPressure",
                "batteryVoltage",
                "humidity",
                "lightRadiation",
                "position",
                "rainGauge",
                "soilMoisture",
                "temperature",
                "totalSolarRadiation",
                "windDirection",
                "windSpeed"
            ]
        }
    ],
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves all available devices for the provided customer.

Get a device

Copy to Clipboard
curl "https://api.adiuvo.it/devices/AA428E915840A1681C11C923378FCEBA" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "device": {
        "alias": "Device alias",
        "clientChannel": "mqtt",
        "clientId": "AA428E915840A1681C11C923378FCEBA",
        "createMillis": 1660309465371,
        "deviceId": "AA428E915840A1681C11C923378FCEBA",
        "firmwareVersionCode": 1000005000,
        "lastConnectionMillis": 1669719698796,
        "lastEventMillis": 1669719698796,
        "topics": [
            "atmosphericPressure",
            "batteryVoltage",
            "humidity",
            "lightRadiation",
            "position",
            "rainGauge",
            "soilMoisture",
            "temperature",
            "totalSolarRadiation",
            "windDirection",
            "windSpeed"
        ]
    },
    "data": {
        "windDirection": {
            "uom": "°",
            "values": [
                {
                    "value": {
                        "label": "East",
                        "degree": 279.7
                    },
                    "timestamp": 1669719661
                }
            ]
        },
        "humidity": {
            "uom": "%",
            "values": [
                {
                    "timestamp": 1669719649,
                    "value": 73.9
                }
            ]
        },
        "temperature": {
            "uom": "°C",
            "values": [
                {
                    "timestamp": 1669719650,
                    "value": 12.5
                }
            ]
        },
        "soilMoisture": {
            "uom": "%",
            "values": [
                {
                    "timestamp": 1669719671,
                    "value": 14.8
                }
            ]
        },
        "rainGauge": {
            "uom": "mm/h",
            "values": [
                {
                    "value": 0,
                    "timestamp": 1669719681
                }
            ]
        },
        "batteryVoltage": {
            "uom": "V",
            "values": [
                {
                    "timestamp": 1669719663,
                    "value": 11.95
                }
            ]
        },
        "position": {
            "uom": "lat,long,m",
            "values": [
                {
                    "value": {
                        "longitude": 12.64995,
                        "latitude": 37.6021813
                    },
                    "timestamp": 1669719666
                }
            ]
        },
        "windSpeed": {
            "uom": "m/s",
            "values": [
                {
                    "value": 0,
                    "timestamp": 1663329636
                }
            ]
        },
        "totalSolarRadiation": {
            "uom": "W/m²",
            "values": [
                {
                    "timestamp": 1669719662,
                    "value": 98
                }
            ]
        },
        "atmosphericPressure": {
            "uom": "Pa",
            "values": [
                {
                    "timestamp": 1669719651,
                    "value": 100470
                }
            ]
        },
        "lightRadiation": {
            "uom": "lux",
            "values": [
                {
                    "value": 7476,
                    "timestamp": 1669719652
                }
            ]
        }
    },
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves a specific device by its clientId and returns the latest data for each topic.

Get topic data from device

Copy to Clipboard
curl "https://api.adiuvo.it/devices/AA428E915840A1681C11C923378FCEBA/temperature" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "device": {
        "alias": "Device alias",
        "clientChannel": "mqtt",
        "clientId": "AA428E915840A1681C11C923378FCEBA",
        "createMillis": 1660309465371,
        "deviceId": "AA428E915840A1681C11C923378FCEBA",
        "firmwareVersionCode": 1000005000,
        "lastConnectionMillis": 1669719698796,
        "lastEventMillis": 1669719698796,
        "topics": [
            "atmosphericPressure",
            "batteryVoltage",
            "humidity",
            "lightRadiation",
            "position",
            "rainGauge",
            "soilMoisture",
            "temperature",
            "totalSolarRadiation",
            "windDirection",
            "windSpeed"
        ]
    },
    "data": {
        "temperature": {
            "uom": "°C",
            "values": [
                {
                    "timestamp": 1669719650,
                    "value": 12.5
                }
            ]
        }
    },
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves a specific device by its clientId and returns the latest data for the requested topic.

Resources

Get available resources

Copy to Clipboard
curl "https://api.adiuvo.it/resources" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "resources": [
        {
            "name": "Grapevine field",
            "createMillis": 1664920799000,
            "resourceId": "2f41363a-3d0d-4485-a932-aa026d55ee04",
            "position": {
                "latitude": 37.6021813,
                "longitude": 12.64995
            },
            "topics": [
                "atmosphericPressure",
                "batteryVoltage",
                "humidity",
                "lightRadiation",
                "position",
                "rainGauge",
                "soilMoisture",
                "temperature",
                "totalSolarRadiation",
                "windDirection",
                "windSpeed"
            ]
        }
    ],
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves all available resources.

Get a resource

Copy to Clipboard
curl "https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "resources": [
        {
            "name": "Grapevine field",
            "createMillis": 1664920799000,
            "resourceId": "2f41363a-3d0d-4485-a932-aa026d55ee04",
            "position": {
                "latitude": 37.6021813,
                "longitude": 12.64995
            },
            "topics": [
                "atmosphericPressure",
                "batteryVoltage",
                "humidity",
                "lightRadiation",
                "position",
                "rainGauge",
                "soilMoisture",
                "temperature",
                "totalSolarRadiation",
                "windDirection",
                "windSpeed"
            ]
        }
    ],
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves a specific resource by its resourceId and returns the latest data for each topic.

Get topic data from resource

Copy to Clipboard
curl "https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04/humidity" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "resource": {
        "name": "Grapevine field",
        "createMillis": 1664920799000,
        "resourceId": "2f41363a-3d0d-4485-a932-aa026d55ee04",
        "position": {
            "latitude": 37.6021813,
            "longitude": 12.64995
        },
        "topics": [
            "atmosphericPressure",
            "batteryVoltage",
            "humidity",
            "lightRadiation",
            "position",
            "rainGauge",
            "soilMoisture",
            "temperature",
            "totalSolarRadiation",
            "windDirection",
            "windSpeed"
        ]
    },
    "data": {
        "humidity": {
            "uom": "%",
            "values": [
                {
                    "timestamp": 1669723257,
                    "value": 80.6
                }
            ]
        }
    },
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves a specific resource by its resourceId and returns the latest data for the requested topic.

Get timeSlot topic data from resource

Copy to Clipboard
curl "https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04/temperature/timeSlot?fromDate=20230401&toDate=20230414&range=4" \
  -H "X-Api-Key: customer-api-key"

The above command returns JSON structured like this:

Copy to Clipboard
{
    "resource": {
        "name": "Grapevine field",
        "createMillis": 1664920799000,
        "resourceId": "2f41363a-3d0d-4485-a932-aa026d55ee04",
        "position": {
            "latitude": 37.6021813,
            "longitude": 12.64995
        },
        "topics": [
            "atmosphericPressure",
            "batteryVoltage",
            "humidity",
            "lightRadiation",
            "position",
            "rainGauge",
            "soilMoisture",
            "temperature",
            "totalSolarRadiation",
            "windDirection",
            "windSpeed"
        ]
    },
    "data": {
        "temperature": {
            "uom": "°C",
            "values": [
                {
                    "value": 13.3,
                    "timestamp": 1680307200000
                },
                {
                    "value": 14.1,
                    "timestamp": 1680321600000
                },
                {
                    "value": 20.5,
                    "timestamp": 1680336000000
                },
                {
                    "value": 19.1,
                    "timestamp": 1680350400000
                },
                // ...
                {
                    "value": 20.2,
                    "timestamp": 1681372800000
                },
                {
                    "value": 19.4,
                    "timestamp": 1681387200000
                },
                {
                    "value": 15.9,
                    "timestamp": 1681401600000
                },
                {
                    "value": 15.5,
                    "timestamp": 1681416000000
                }
            ]
        }
    },
    "cloudRegion": "gcp-europe-west8",
    "apiVersion": "v0.4.1-alpha",
    "kRevision": "api2-00014-haw",
    "millis": 1669728798994
}

This endpoint retrieves a specific resource by its resourceId and returns the time slot data for the requested range, in the requested dates interval and for the requested topic.

Query Parameters

Parameter Format Default Description
fromDate YYYYMMDD 7 days before the request The initial day of the interval to retrieve data for.
toDate YYYYMMDD The full day before the request The final day of the interval to retrieve data for.
range number 24 The daily range of data to retrieve. The value must be a divisor of 24: 1, 2, 3, 4, 6, 8, 12, 24.

Get daily topic data from resource

shell http