How GE Current APIs Power Smart City Applications

Continued from page 1. 

Using the Cloud Foundry CLI you can get details about your app and any services bound to it. In this case, we’re interested in the ie-traffic service. More specifically we need to run cf env <my-predix-current-app> to retrieve the url and Predix-Zone-Id.

"ie-traffic": [
{
 "credentials": {
  "url": "https://ie-traffic.run.aws-usw02-pr.ice.predix.io",
  "zone": {
   "http-header-name": "Predix-Zone-Id",
   "http-header-value": "123-abc",
   "oauth-scope": "ie-traffic.zones.123-abc.user"
  }

Combined with our token from before we have the authorization and access needed to start retrieving traffic data by using these headers in all future requests.

uaa = 'https://my-uaa.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token'
token = get_client_token(uaa, "myapp", "mysecret")

traffic_url = "https://ie-traffic.run.aws-usw02-pr.ice.predix.io"
traffic_zone = "123-abc"

headers = {
   'Authorization': 'Bearer ' + token,
   'Predix-Zone-Id': zone
   }

But where is the data coming from?

/v1/assets/search

If you picture a streetlight, this is something Predix would refer to as an Asset. An Asset is a generic term like widget or foobar that helps us organize a directed graph of nodes. There is an entire Asset API if you wanted to create an asset model for your own use cases – but for our purposes we have a streetlight node that has a camera and other sensors all represented as assets.

Before we can start observing traffic events, we need to identify the asset we want to listen to. After all, there is more than one streetlight in a city therefore, we have to search for an asset of interest.

The Traffic API provides an endpoint with a relative URI of /v1/assets/search that requires a few parameters. We can query by device-type, media-type, or an event-type. We also want to narrow our search down by location with a bounding box (bbox) though we could walk the entire graph and page through results if we wanted to be thorough.

San Diego, that place where Happiness is Calling, has been a pioneer in adopting a smart city prototype scattered around the city. Some helpful simulated data can be retrieved with a bbox that correlates data from that geolocation.

Let’s find an interesting asset (or maybe just the first one).

def get_assets(url, headers, bbox, device_type):
   url = url + '/v1/assets/search'
   params = {
       'q': 'device-type:' + device_type,
       'bbox': bbox,
       }
   response = requests.get(url, headers=headers, params=params)
   return json.loads(response.text)['_embedded']['assets']

The original API design follows a HATEOAS pattern where the assets retrieved by this function have _links to follow for finding additional information. This includes links to retrieve live-events or continue to search-events or search-media. For much more detail you should review the online documentation.

Putting that all together again, we get our UAA token and then query for some assets at a given location like so:

bbox = '32.715675:-117.161230,32.708498:-117.151681'
assets = get_assets(traffic_url, headers, bbox, 'DATASIM')

We can use the data in assets[0]['_links']['live-events']['href'] to get the Websocket address. This is needed in order to listen to the stream of events identifying when cars drive by with the Traffic Flow API.

from websocket import create_connection

wss = get_asset_live_stream(assets[0], headers)
ws = create_connection(wss, header=headers)
event = ws.recv()
ws.close()

This example is just grabbing the next event to explore. The JSON includes an epoch timestamp, traffic lane, vehicle type, count, speed, and direction.

{
 "event-uid":"fe5742c0-aff2-4747-8cb2-54e2dac8c758",
 "timestamp":1468481476061,
 "event-type":"TFEVT",
 "device-uid":"HYP1040-75",
 "location-uid":"HYP1040-75-Lane2",
 "properties":{
       "vehicle-type":"car" },
 "measures":[
       {"tag":"vehicleCount", "value":4},
       {"tag":"speed", "value":19, "unit":"MPS"},
       {"tag":"direction","value":271,"unit":"DEGREE"} ]
}

Naturally you’d want to adapt this to listen to all the events and assets you are interested in for your use cases.

Wrapping Up

I hope this walkthrough was helpful and the source code snippets from this post can be found on GitHub.

The TrafficSeedApp takes some of these APIs and wraps them all up in a nice user interface demo. This can be a helpful resource to launch your own exploration of the APIs. It is built with a toolchain including node.js, gulp, and bower for those looking for an example other than Python.

Get the source so you can review the README.md and hack at it yourself:
git clone https://github.com/CurrentByGE/TrafficSeedApp.git

There is a digital gold rush for developers to build intelligent applications for the Industrial Internet of Things. APIs like these for traffic, parking, pedestrians, and general safety are the building blocks for more sophisticated applications.

Learn more about case studies using the APIs at the Predix Transform conference track on Intelligent Environments July 25-27, 2016 or jump right in on the Intelligent World Hackathon which is open to all developers and running now with $58,000 in prizes. The hackathon ends August 2, 2016 so don’t procrastinate too long, but given what Ciklum did in 48 hours you have plenty of time.

Jayson DeLancey Developer Evangelist for Predix, GE Digital's Industrial Internet of Things (IIoT) Platform

Comments