Geocoding with Thingstream

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

Sign up for an OpenCage account, and get your OpenCage API key

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

Thingstream - 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:

Thingstream - create an HTTP request

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:

  • KEY Your OpenCage API key

  • LAT The latitude captured by the VTrackL tracker, which can be retrieved by specifying {{{payload.lat}}}

  • LON The 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.

Thingstream - print output

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.

Start your free trial

2,500 geocoding API requests per day.

No credit card required.