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 Settings’, en vervolgens het tabblad ‘Developer’ te kiezen.

Klik  op de knop “Request new API key”.

Vervolgens verschijnt er een popup scherm met je API key. Deze kun je kopieëren en gebruiken om data op te halen via de API.

API Documentatie

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

Checks ophalen met postman

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

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  de data als een tabel wilt weergeven, 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 ziet er dan zo uit:

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.