API Specification and concepts on sending IoT data to the holidaymaker infrastructure to then be used and rendered on various holidaymaker surfaces.
IoT Data ingestion is a useful module within the holidaymaker infrastructure. It works by a provider sending the data regually to your holidaymaker web service, which will then distribute it throughout the rest of your holidaymaker sources and surfaces.
The IoT data we receive can be any string of numbers or characters, so essentially can be any reading from any device. When the values are rendered, you have the options to add your own custom setup to each collection of data, for example adding a prefix or suffix to values.
Example data could be :
Before you can send IoT data to a holidaymaker it must be enabled, and setup by the holidaymaker team. Please contact us if you are an IoT provider wishing to send data for a client, or are a client who wishes to have the module enabled.
When sending us data you can send as data for all devices in one packet, or each device can send its own individual packet. This is very flexible based on provider, location and context.
You will be provided with a unique endpoint for each provider and each location you wish to send us data for. The packet you then send down determines which context the reading is for.
All requests made to our endpoint are POST with a JSON packet of data for the body.
The endpoints will only allow data ingestion if you have an authorised API Key setup by the holidaymaker team. This will be provided to you and will need to be included in the HTTPS headers of all data pushes. See code examples below.
Example header : ApiKey: 12345ABCDEF
The body of the request contains your data readings in JSON format. These are keyed using predetermined contexts as highlighted above. You can send a single context per request, or send multiple contexts in one packet.
The packet should be a single JSON object with the values keyed using the predetermined context keys. The value is always force read as a string, however none string primitive values can be sent such as integers, doubles, and booleans, which will be forced to be read and stored as a string.
In the examples below we are sending three contexts which have been defined before sending the data:
//Single Packet (note that both strings and numbers are valid)
{
"outdoorpool": 30.1,
"indoorpool": "31.6",
"playingfieldwind": "34mph"
}
//Seperate Packets
{"outdoorpool": 30.1}
{"indoorpool": "31.6"}
{"playingfieldwind": "34mph"}
//Mix - Maybe one from a service check pools, and one checking weather
{
"outdoorpool": 30.1,
"indoorpool": "31.6"
}
{"playingfieldwind": "34mph"}When you POST data to our endpoint we will respond accordingly. Due to the simplicity of the request and context of the endpoint the results are limited.
You will receive one of two HTTP codes back
If you receive a 400 error the packet will also include a plain text error message as a returning JSON packet with the property error :
If a 200 is received it means we can attempt to process the JSON and you will receive a 200 back. This does not however mean that we have stored the data, this instead is included as information in the response back to you, so you can error handle on your own end and contextualise what has been sent.
// 200 - Everything OK - single value sent
{
"hookKey": "iotprovider",
"groupSite": "single-site",
"contextsStored": [
{
"value": "30.5",
"context": "poolTemperature"
}
]
}
// 200 - Everything OK - Multiple Values sent with a different internal context for HM to use
{
"hookKey": "iotprovider",
"groupSite": "single-site",
"contextsStored": [
{
"value": "30.5",
"context": "poolTemperature",
"internalContext": "pooltemp"
},
{
"value": "7.11",
"context": "poolPH"
}
]
}
// 200 - Everything OK - Multiple Values sent but an additional unknown context was also sent
{
"hookKey": "iotprovider",
"groupSite": "single-site",
"contextsStored": [
{
"value": "30.5",
"context": "poolTemperature"
},
{
"value": "7.11",
"context": "poolPH"
}
],
"messages": [
"Unknown Context/Value Received: madeUpContext : 11"
]
}
// 200 - Everything OK and processed - However no contexts were actually recognised
{
"hookKey": "iotprovider",
"groupSite": "single-site",
"contextsStored": [],
"messages": [
"Unknown Context/Value Received: poolTemperat ure : 30.5",
"Unknown Context/Value Received: po olPH : 7.11",
"Unknown Context/Value Received: madeUpContext : 11",
"Error: No contexts registered in this packet!"
]
}
//400 - Incorrect ApiKey
{
"error": "Unauthorised"
}
//400 - Bad Json Sent
{
"error": "Cannot parse body as JSON"
}In the below examples IoT data for multiple pool readings are being sent to a single endpoint :
These examples are for making a generic HTTP request using CURL, or language specific using PHP, JavaScript, or Python.
These examples include the ApiKey hardcoded. Please take care when storing/using our API key and ensure that it would never be visible on any front facing script to the public (eg a JavaScript unit on a website front end)
//Generic CURL request
curl -X POST https://your-holidaymaker-webservice.endpoint/hooks/iotcompany/parkname \
-H "Content-Type: application/json" \
-H "ApiKey: 1122334455667788" \
-d '{"pooltemperature":"30.5","poolph":"7.11"}'<?php
//PHP Using CURL
$hmEndpoint = "https://your-holidaymaker-webservice.endpoint/hooks/iotcompany/parkname";
$iotData = [
"pooltemperature" => "30.5",
"poolph" => "7.11"
];
$ch = curl_init($hmEndpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"ApiKey: 1122334455667788"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($iotData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//Check for errors etc
$response = curl_exec($ch);
curl_close($ch);
//Do something with response if required
echo $response;//Generic JavaScript
const hmEndpoint = "https://your-holidaymaker-webservice.endpoint/hooks/iotcompany/parkname";
const iotData = {
pooltemperature: "30.5",
poolph: "7.11"
};
fetch(hmEndpoint, {
method: "POST",
headers: {
"Content-Type": "application/json",
"ApiKey": "1122334455667788"
},
body: JSON.stringify(iotData)
})
.then(response => response.json())
.then(result => {
console.log(result);
})
.catch(error => {
console.error("Error:", error);
});//Python Example
import requests
hmEndpoint = "https://your-holidaymaker-webservice.endpoint/hooks/iotcompany/parkname"
iotData = {
"pooltemperature": "30.5",
"poolph": "7.11"
}
headers = {
"Content-Type": "application/json",
"ApiKey": "1122334455667788"
}
response = requests.post(hmEndpoint, json=iotData, headers=headers)
//Do something with response
print(response.text)You've reached the end of the preview. Sign in or join us to read the full article and access other comminity content.