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

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

GET https://api.adiuvo.it HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/devices HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/devices/AA428E915840A1681C11C923378FCEBA HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/devices/AA428E915840A1681C11C923378FCEBA/temperature HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/resources HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04 HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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

GET https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04/humidity HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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

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"

GET https://api.adiuvo.it/resources/2f41363a-3d0d-4485-a932-aa026d55ee04/temperature/timeSlot?fromDate=20230401&toDate=20230414&range=4 HTTP/1.1
X-Api-Key: customer-api-key

The above command returns JSON structured like this:

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