Sensor data ophalen via de API


Data via de API ophalen kan op verschillende manieren. Het is mogelijk de huidige waarde van een sensor op te halen maar ook de historische waardes over een periode.

Om data van een sensor op te halen hebben we als eerste het id nodig van de sensor. Een manier om deze te verkrijgen is om naar het ZENSIE dashboard te gaan (sensors > klik op de sensor waarvan je het id wilt weten) en de url in de browser te bekijken:

Sensor URL voorbeeld

Een andere optie is om alle sensoren van een organisatie op te halen via een api verzoek (bekijk deze pagina voor een voorbeeld)

Om API verzoeken te doen, is een API key nodig. Deze kan aangevraagd worden in het ZENSIE dashboard (Account settings > developer).

Hier zijn een paar voorbeeld verzoeken om data op te halen van een temperatuur/luchtvochtigheid sensor met id “39555cf5-3081-400c-96cf-ff8d9cdea173”. We gebruiken deze API endpoint:

We dienen een GET verzoek uit te voeren met het sensor id en een datum/tijds interval. In dit voorbeeld verzoeken we de gemiddelde temperatuur per dag van 1 tot 4 november 2017.

curl -XGET \
    -H "Content-type: application/json" \
    -H 'Authorization: <API key>' \
    "https://api.30mhz.com/api/stats/check/39555cf5-3081-400c-96cf-ff8d9cdea173/from/2017-11-01T00:00:00Z/until/2017-11-04T00:00:00Z?statisticType=averages&intervalSize=1d"

 

Als resultaat krijgen we dan:

{ 
  "1509494400000": 
    { "sht25.temp": 18.601995752298404, 
      "sht25.humidity": 59.27995778537517 
    }, 

    "1509580800000": 
      { "sht25.temp": 18.30961109134886, 
      "sht25.humidity": 58.49782640139262 
      }, 

    "1509667200000": 
      { "sht25.temp": 17.93818057510588, 
        "sht25.humidity": 58.11836816999647 
      }
}

We zien hier de gemiddelde temperatuur en luchtvochtigheid per dag. De key toont de dag + tijdstip van de waardes.

Het is ook mogelijk om de minimum of maximum waardes voor een periode op te halen. We gebruiken hiervoor statistictype=mins of statisticTypes=maxs.

We kunnen ook de interval grootte aanpassen en de data per uur verzoeken met intervalSize=1h of per minuut (1m), 5 minuten (5m), 5 dagen (5d) , maand (M), etc.

Om de huidige waarde van een sensor op te halen kunnen we deze API endpoint gebruiken:

Een voorbeeld:

curl -XGET \
    -H "Content-type: application/json" \
    -H 'Authorization: <API key>' "https://api.30mhz.com/api/stats/check/56aac51f-5966-47da-8824-eaf36c8e4737"

We krijgen dan dit als resultaat:

{ "checkId": "56aac51f-5966-47da-8824-eaf36c8e4737", 
  "timestamp": "2017-11-21T13:10:45Z", 
  "lastRecordedStats": 
      { "sht25.temp": "16.79", 
        "sht25.humidity": "62.93" 
      }, 
  "json": null, 
  "code": null, 
  "message": null, 
  "matchCondition": null
}

De lastRecordedStats eigenschap bevat de huidige waardes.

Alle API endpoints om data van 1 of meerdere sensoren op te halen is te vinden in de Swagger documentatie.

Ingest api: externe sensor data toevoegen in ZENSIE


Creëren  import checks
De eerste stap is het creëren van import checks. Een import check bevat alle data van een sensor en creëert een api pad waar waardes naartoe verzonden kunnen worden. Import checks kunnen aangemaakt worden door te navieren naar de checks pagina in het dashboard. Rechts onder kan de plus knop aangeklikt worden om een nieuwe sensor toe te voegen. Hierna kunnen we op de external sensor optie klikken.

We vullen de naam in, selecteren de sensor type en klikken op create.

Sensor types
Sensor types bevatten alle informatie over hoe data weergegeven wordt. Een sensor type bevat informatie zoals de metriek + eenheid (Temperatuur = ºC), data types en verwachte json waardes. Als er een nieuwe sensor types toegevoegd moet worden, stuur ons een bericht.

Data versturen naar een import check

De laatste stap is het versturen van de data naar de api. Nadat de check is opgeslagen zien we de settings pagina. Hier zien we het pad met voorbeeld data.

We kunnen een post doen naar:

https://api.30mhz.com/api/ingest/organization/www.30mhz.com

 

Met deze waardes (dit verandert aan de hand van de import check en sensor type):

[ 
  { 
  "checkId": "import_check_id", 
  "timestamp": "A valid ISO 8601 DateTime format value with an explicitly set timezone value (e.g. 2017-01-17T19:23:02Z, 2017-01-17T19:23:02+06:45)", 
  "data": 
    {
      "temp": "double", 
      "hum": "double" 
    }, 
  "status": "ok || fail", 
  "error": "custom error text message" 
  } 
]

 

De waardes zitten binnen een array. Hierdoor kunnen we (optioneel) meerdere sensor data (import checks) in 1 call doen:

[{import_check_1...},{import_check_2...},{etc...}]

 

API Keys
Om de api te gebruiken zijn api keys vereist. Lees hoe api keys in de Authorization header moeten worden toegevoegd.

 

Analyseer (explore) je data in ZENSIE


In de explore weergave, kun je je data visualiseren door grafieken te creëren en verschillende tijdsperiodes en intervals te selecteren.

Sensor data visualiseren

Om je data te visualiseren in een grafiek, selecteer je één of meer sensor checks uit het drop down menu:

Als je meer sensor data aan de grafiek wilt toevoegen, klik je op de knop “+ SENSOR TOEVOEGEN”:

Tijdsperiodes en intervals voor je grafieken selecteren

De grafiek toont automatisch data van de laatste 24 uur met een interval van 5 minuten. Je kunt:

  1. De tijdsperiode aanpassen.
  2. De tijd intervals aanpassen.
  3. Selecteren om gemiddeldes, of minimum/maximum waarden weer te geven.

Data exporteren vanuit ZENSIE


Op de Export pagina, kun je de rauwe data van je organisatie exporteren.

Selecter de maand, het jaar en de locatie waarvan je data wilt exporteren en klik op START EXPORT.

Wanneer je data gereed is om gedownload te worden, ontvang je een e-mail.

Data ophalen met de ZENSIE API


30MHz biedt een REST API om toegang te krijgen tot de data die ZENSIE verzamelt via web checks en sensoren.

Om hiervan gebruik te maken, moet er eerst een API sleutel gecreëerd worden. Je kunt dit doen door naar de zijbalk te gaan, te klikken op Account Instellingen, en vervolgens het tabblad Ontwikkelaar te kiezen.

Als dit de eerste keer is dat je een API sleutel aanvraagt, klik je op de knop “Selecteer een nieuwe API sleutel”. Je wordt dan gevraagd om opnieuw in te loggen met je inloggegevens. Daarna verschijnt er een sleutel op de pagina, die je kunt kopiëren om verbinding te maken met de API.

API Documentatie

De API documentatie is te vinden op https://api.30mhz.com/api/swagger. Er zijn twee (2) manieren om de API te proberen; door postman te gebruiken, of via de opdrachtregel/command line(?).

Checks ontvangen met postman

In dit voorbeeld laten we zien hoe je postman kunt gebruiken om alle checks van je organisatie te ontvangen.

Ga naar swagger documentatie en vind de beschrijving van het eindpunt dat alle checks van een bepaalde organisatie ophaalt https://api.30mhz.com/api/swagger#!/check/getOrganizationChecks.

Let op de URL die je nodig hebt om een call(?) te maken en op de verplichte velden. In dit voorbeeld is het id van de organisatie een verplicht veld.

Om je organisatie id te vinden, ga je naar het ZENSIE dashboard, en klik je op Account Instellingen onder het tabblad Organisatie.

Een andere manier om het id van je organisatie te vinden, is via de url op de ZENSIE pagina:

Hier kun je een gratis versie van postman downloaden. Open de applicatie en vul de vereiste velden in:

GET https://api.30mhz.com/api/check/organization/{{organization id}}

Headers

Authorization: {{your API key}}

Content-Type: application/json

Het antwoord is een JSON object dat er ongeveer als volgt uit zou moeten zien:

De opdrachtregel gebruiken om checks te ontvangen

Hier laten we zien hoe je alle checks van je organisatie kunt ontvangen door gebruik te maken van de opdrachtregel:

  1. Open een opdrachtregel interface (bijv. een terminal voor Mac, of een opdrachtprompt voor Windows).
  2. Om alle checks van je organisatie te ontvangen heb je de volgende CURL opdracht nodig:

Als je de output van een opdracht in een bestand wil opslaan, voeg je >>output.txt toe aan het einde van de opdracht:

De data in het output.txt bestand wordt opgeslagen in JSON formaat. Als je hier niet bekend mee bent en je wilt de data als een tabel weergeven, dan kun je een online JSON naar CSV converter gebruiken (bijvoorbeeld deze).

Het enige wat je hoeft te doen is de data van het output.txt bestand te kopiëren en te plakken in het daarvoor bestemde veld op de pagina van de converter. Het resultaat zou er ongeveer zo uit moeten zien: