Skip to main content
Version: 1.0.0

Making your first API call

In this guide, we will walk you through the process of making your first API request. We will begin by showing you how to retrieve a list of all your assets (Buildings, Floors, Rooms, Desks, etc.), and then we will demonstrate how to retrieve sensor data from some of these assets using the Query API endpoint.

caution

Prerequisite​

Please note that the following API calls require you to make an authenticated call to the Relynks API. If you haven't already, please follow the Authentication guide to learn more about our API authentication process.

Retrieving a list of all your assets​

To retrieve a list of all your assets, you will need to make a GET request to the endpoint '/asset/list'. Here is an example of how to make this request using cURL:

curl -X GET \
  https://api.relynk.io/asset/list \
  -H 'accept: application/json' \
  -H 'authorization: YourAPIKey' \
  -d asNestedObjects=true
caution

Please make sure to replace 'YourAPIKey' with the actual value of your API key.

This request will return a list of all your assets as a nested object (as an example, a buildings will have its floors as children and the rooms as childrens of the floors etc.). The response will follow the schema specified below:

id
required
string
name
required
string
number
string or null
type
required
string
Enum: "Building" "Floor" "Area" "Room" "Desk" "Facade"
children
Array of objects (Asset)
parent
object Recursive
Array of objects (AssetParam)
Array of objects (DrawingLayer)
object
Array of objects (Sensor)
{
  • "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  • "name": "sample_building_1",
  • "number": null,
  • "type": "Building",
  • "children": [ ],
  • "parent": { },
  • "asset_params": [ ],
  • "drawing_layers": [ ],
  • "drawing_image": { },
  • "sensors": [
    ]
}
tip

If you want all the assets to be returned as a one-dimensional array, you can set the asNestedObjects parameter to false.

info

To view the full documentation for the Asset List API endpoint, please visit API Reference - Asset GetMany Endpoint.

Retrieving sensor data using the Query API endpoint​

Once you have a list of assets, you can create a query request to retrieve sensor data and filter the results to only retrieve data from specific assets.

tip

Read the Relationship between sensors and assets deep dive to understand how sensors are related to the assets.

In this example, we will retrieve the average temperature and presence data from all the rooms on the 4th floor of a building, from the 1st of January at a 1-hour resolution.

First, you will need to retrieve the asset ID of the 4th floor. You can do this by looking at the data from the previous request you made to '/asset/list' and locate the 4th floor. Once you have the ID, you can make the following POST request to the '/query' endpoint:

curl -X 'POST' \
  'https://api.relynk.io/query' \
  -H 'accept: application/json' \
  -H 'authorization: YourAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
        {
        "filter_on": "asset_id",
        "value": [
            YourFloorId
        ]
        },
        {
        "filter_on": "measurement",
        "value": [
            "Presence", "Temperature"
        ]
        }
    ],
    "group_on": "Room",
    "resolution": "1 hour",
    "is_timeseries": true,
    "only_latest_value": false,
    "to": "2023-01-02T00:00:00+01:00",
    "from": "2023-01-01T00:00:00+01:00"
  }'
caution

Make sure to replace 'YourAPIKey' with the actual value of your API key, and 'YourFloorId' with the actual value of the floor id.

This will return a list of all the rooms on the 4th floor with the average temperature and presence data from the 1st of january at a 1 hour resolution with the following schema:

measurement_type
required
string
Enum: "Temperature" "RelativeHumidity" "AirQuality" "SoundLevel" "Presence" "PeopleCount" "Booked" "BatteryLevel" "Light" "SunScreenDown" "AirFlow" "AirPressure" "FluidFlow" "FluidPressure" "WindDirection" "WindSpeed" "WindGustSpeed" "PrecipitationRate" "Power" "Energy" "EnergyReactive" "Voltage" "Current" "Frequency" "Efficiency" "PowerFactor" "Gain" "Ratio" "Weight" "Waste_MixedPlastic" "Waste_Cardboard" "Waste_Unsorted" "Waste_MixedWasteForSorting" "Waste_Organic" "Waste_ExpandedAndExtrudedPlastic" "Waste_GlassAndMetal" "Waste_EWaste" "Waste_OfficePaper" "CO2" "WIFI_Connected_Clients"
unit
required
string
Enum: "kilogram" "dB" "Percent" "TVOC" "Yes / No" "Number" "Celcius" "Farenheit" "Kelvin" "Volt" "Lux" "PPM" "PPB" "m3" "m3/s" "m3/min" "m3/h" "m3/day" "Degrees Angular" "Farad" "Herzt" "Horsepower" "Joul" "MilliJoul" "KiloJoul" "Watt" "MilliWatt" "KiloWatt" "MegaWatt" "kWh" "kWh_Reactive" "Wh" "Wh_Reactive" "MWh" "MWh_Reactive" "Liter" "l/s" "l/min" "l/h" "Lumen" "m/s" "m/min" "m/h" "m/s2" "MilliAmpere" "Ampere" "MilliVolt" "Newton" "NewtonMeter" "NewtonSecond" "Ohm" "MilliOhm" "KiloOhm" "MegaOhm" "Pa" "%/s" "pH" "PowerFactor" "Radian" "Radian/s" "RPM" "Siemens" "SquareMeter" "m2/Newton" "Tesla" "Tonn" "VoltAmpere" "VoltAmpere_Reactive" "VoltAmpereHour" "VoltAmpereHour_Reactive"
group_asset_id
string
group_asset_name
string
group_asset_type
string
Enum: "Building" "Floor" "Area" "Room" "Desk" "Facade"
group_sensor_id
string
group_sensor_name
string
value
number
average_value
number
count_value
number
sum_value
number
min_value
number
max_value
number
date_time
required
string <date-time>
{
  • "measurement_type": "Temperature",
  • "unit": "Celcius",
  • "group_asset_id": "",
  • "group_asset_name": "",
  • "group_asset_type": "Building",
  • "group_sensor_id": "",
  • "group_sensor_name": "",
  • "value": 24.5,
  • "average_value": 22.5,
  • "count_value": null,
  • "sum_value": null,
  • "min_value": 18.5,
  • "max_value": 24.7,
  • "date_time": "2019-08-24T14:15:22Z"
}
tip

Read the Querying data deep dive to learn more about the Query API endpoint.

To view the full for the Query API endpoint, please visit the API Reference - Query Endpoint page.

API Reference​

To view all the actions you can perform with the Relynks API, please visit the API Reference page.