Geocode device coordinates in Thingstream with OpenCage
Background
Thingstream is an Internet-of-Things (IoT) communications platform. It makes enables organizations to collect and manage data from many IoT devices.
In this tutorial we show how to convert Thingstream device coordinates (from GPS or wifi) into location information usign a Thingstream flow and the OpenCage geocoding API.
Step 1: Sign up for an OpenCage account
If you already have an account then log in.
Step 2: Sign up for a Thingsteam account
Go to portal.thingstream.io and create an account.
Most of the Thingstream components that we are going to use require an upgrade to their paid platform, so add your credit card in order to be able to do HTTP requests and more.
Step 3: Create a flow
If you have a Versades VTrackL or another tracker feel free to re-use a flow from the flow library. In the case of the Versades VTrackL GPS tracker the GPS information captured is like this:
{
"time":1583849709,
"lon":2.100892933085561,
"lat":41.52874996885657,
"locType":"GPS",
"clientId":"1234567",
"name":"ICCID: 1234567",
"type":"DeviceStatusUpdate",
"serialNumber":"868183038251372"
}
In your flow get the JSON from the JSON box and create a HTTP request box:
The OpenCage URL that you will be requesting from has the format
https://api.opencagedata.com/geocode/v1/json?key={{KEY}}&q={{LAT}}%2C%20{{LON}}
The URL has three parameters:
-
KEYYour OpenCage API key -
LATThe latitude captured by the VTrackL tracker, which can be retrieved by specifying{{{payload.lat}}} -
LONThe longitude captured by the VTrackL tracker, which can be retrieved by specifying{{{payload.lon}}}
So the final URL will look like:
https://api.opencagedata.com/geocode/v1/json?key=YOUR-API-KEY&q={{{payload.lat}}}%2C%20{{payload.lon}}
Requests to the OpenCage geocoding API you will return JSON with information about the location.
A debug box with, for example,
msg.payload.results[0].formatted
will return a human-readable, well-formatted address of the location.
4. Get other types of information from OpenCage
We intentionally kept this guide very basic, just getting the formatted location name. But you can also get a lot more information from OpenCage - things like timezones, flag, neighbourhood name, road information, etc.
It's worth spending some time looking at the OpenCage response format and all the various annotations that the OpenCage geocoding API can provide.
Have questions? Please get in touch
Please contact us should you have any questions about this tutorial or OpenCage in general.