API integration

The Efento Cloud API enables you to securely retrieve measurement data from sensors connected to your Organization. Using the API, you can pull data from all sensors or only selected devices, depending on your needs. Before accessing any data, you must generate an API token, which authorizes your requests and ensures secure communication with the platform.

In this chapter, you will find step-by-step examples showing how to use the API to:

• retrieve the most recent measurements from all sensors within a chosen location, and

• download historical measurement data for a specific time period.

These examples will help you quickly integrate Efento Cloud data with your own applications, dashboards, or analytical tools.

1

Get lists of organisations

Check the IDs of the organisations, to which you have access, by sending the following request to Efento API:

Method: GET

Endpoint: https://cloud.efento.io/api/v2/organizations

Headers: Authorization: API token (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the organisations to which you have access along with their IDs and names:

{
   "totalCount": 1,
   "organizations": [
       {
           "id": 2881,
           "name": "Organisation 1",
           "createdAt": "2022-05-25 11:09:27",
           "updatedAt": "2022-05-25 11:09:27",
           "token": "hf04gb0e-bsd3-440c-9fb9-ad0daad420e0",
           "smsSent": 0,
           "smsLeft": 0,
           "licensesLeft": 0,
           "measurementPointsCount": 1
       },
       ]
}

You will need the ID of the organisation in the next request ("id": 2881).

2

Get list of all locations in your organisation

Sensors in organisations are grouped by locations. To receive the list of all locations in your organisation use the following request:

Method: GET

Endpoint: https://cloud.efento.io/api/v2/locations?organization-id=ID-OF-YOUR-ORGANISATION (e.g. https://cloud.efento.io/api/v2/locations?organization-id=2881)

Headers: Authorization: API token (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the locations to which you have access along with their IDs and names:

{
   "locations": [
       {
           "id": 5655,
           "name": "TOP",
           "organizationId": 2881,
           "createdAt": "2022-05-25 11:09:27",
           "parentId": 0
       }
   ],
   "totalCount": 1
}

You will need the ID of the location in the next request ("id": 5655).

3

Get list of the measurement points with their most recent measurements

To receive the list of all measurement points in the selected location use the following request:

Method: GET

Endpoint: https://cloud.efento.io/api/v2/measurement-points?location-ids=ID-OF-THE-LOCATION (e.g. https://cloud.efento.io/api/v2/measurement-points?location-ids=5655 )

Headers: Authorization: API token (e.g. “adsFcdc34rf…”)

By default, the API returns the first 20 measurement points assigned to the organisation. If your organisation contains more than 20 measurement points, you need to use pagination to retrieve the information about all the devices.

To retrieve more measurement points use th following request: https://cloud.efento.io/api/v2/measurement-points?location-ids=ID-OF-THE-LOCATION&limit=20&offset=0 (e.g. https://cloud.efento.io/api/v2/measurement-points?location-ids=5655&limit=20&offset=0)

limit - number of the measurement points you want to retrieve (min. 20, max.100)

offset - offset used to shift the measurement points retrieved by the request (e.g. to retrieve first 100 measurement points use “...&limit=100&offset=0”, to retrieve second 100 measurement points use “...&limit=100&offset=100”, to retrieve third 100 measurement points, use “...&limit=100&offset=200”, etc.)

In the response from Efento API, you will receive JSON that contains the list of all the measurement points assigned to the selected location along with their IDs and names and the value of the most recent measurement:

{
   "measurementPoints": [
       {
           "id": 989330,
           "locationId": 5655,
           "createdAt": "2022-05-25 12:17:22",
           "name": "40EBEC",
           "unconfirmedAlertsCount": 358,
           "activeAlertsCount": 0,
           "status": "OPERATIONAL",
           "measurements": {
               "measuredAt": "2022-06-15 12:15:00",
               "period": 5,
               "channels": [
                   {
                       "number": 1,
                       "name": "40EBEC",
                       "type": "ALARM",
                       "value": 0,
                       "status": "OK"
                   }
               ]
           },
           "device": {
               "id": 1128025,
               "serialNumber": "282C0240EBEC",
               "powerStatus": "BATTERY_OK",
               "signal": 37,
               "nextCommunicationAt": "2022-06-15 13:21:03"
           }
       }
   ],
   "totalCount": 1
}

You will need the ID of the measurement point for the next request ("id": 989330)

4

Get measurements from the selected time period

To receive the the measurement from the selected time period use the following request:

Method: GET

Endpoint: https://cloud.efento.io/api/v2/measurement-points/ID-OF-THE-MEASUREMENT-POINT/measurements?from=DATE-OF-THE-FIRST-MEASUREMENT-IN-UTC&to=DATE-OF-THE-LAST-MEASUREMENT-IN-UTC (e.g. https://cloud.efento.io/api/v2/measurement-points/989330/measurements?from=2022-06-14 22:00:00&to=2022-06-15 21:59:59)

Headers: Authorization: API token (e.g. “adsFcdc34rf…”)

In the response from Efento API, you will receive JSON that contains the list of all the measurements taken in the selected time period