API Overview

Full Suite of APIs for Device and Sensor Data Access and Control

Find Your Solution Today. Create an Account

 

This page provides a high-level overview of the APIs available to developers who partner with Itron

 

Cloud Based APIs


Cloud based APIs include:


Cloud Based API Authentication Security

Authentication

Calls are secured using an OAuth token (API key). Each call must include an Authorization http header that specifies the token. All APIs use tokens are retreived from the token's API included with Starfish Studio. A token is obtained with a Client ID and Secret API key. Your client ID and Secret can be obtained from the Account Settings tab in My Account Overview. If you don't already have one, you can create an account.

 

Tokens

Once you have your Client ID and Secret, you can obtain a token by calling the "tokens" API replacing <your ClientID> and <your Secret> with the values provided through your Developer Portal account. You can find more information about the tokens API and its use in the API View in Starfish Studio.

An example call using Curl is shown here:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"clientId": "<your ClientID>", "clientSecret": "<your Secret>"}' 'https://api.data-platform.developer.ssni.com/api/tokens'

Upon successful client authentication, the authorization server returns the access token in the response. You can now make the actual query by providing the access token obtained from the response given in the previous step in the HTTP Authorization header.

 

Token Expiration

APIs can be called in any combination and any number of times with a valid token; however, tokens are valid for a fixed time duration of one hour. A new token must be obtained upon expiration.

Cloud Based API Architecture

 

 


 

Data Platform

 

The Data Platform APIs enable a new generation of applications by making high granularity sensor data easily available. The Data Platform provides a suite of REST-based APIs for solution development and IoT device data access. There are multiple APIs to power a variety of use cases. The API set includes:

  • Device provisioning and querying
  • Event provisioning and subscription through webhooks
  • Observations (sensor data)
  • Provisioning
  • Querying
  • and more 

 

You can run a simulation using the Data Platform APIs in Starfish Studio. More details on the available Data Platform APIs and their use can be found at Data Platform APIs.

There is a wide array of APIs to power a variety of use cases. Our team is always seeking input from our partner ecosystem, and we encourage you to share feedback.

Data Platform API Architecture

 

 

 


 

CoAP Gateway

 

The CoAP Gateway is a UDP-based Constrained Application Protocol (CoAP) interface that exposes a forward proxy for Read/Write access to devices on the Itron Networked Solutions mesh network.

The CoAP Gateway functions as a standard CoAP-to-CoAP proxy and its usage primarily follows the CoAP standard. Therefore, it can be implemented with standard tools, such as the libcoap library for Linux and OS X or COAPSharp library for .NET.

To learn more about the CoAP API, refer to CoAP Overview and CoAP Gateway API Documentation.

 

Note: Starfish Studio is designed for using Data Platform APIs, and not the CoAP API.

CoAP Subscription Flow

 


 

MQTT Client

 

Message Queuing Telemetry Transport (MQTT) is a Client Server publish/subscribe messaging transport protocol. A central service called an MQTT Broker allows clients to connect and either publish or subscribe to events on "topics".  This decouples the producers of data from the consumers of data - one or more consumers have a subscription to a message topic and receive those messages but they do not need to know the source of the messages. 

The Itron back office includes an MQTT broker that allows applications to publish messages on topics and other applications to subscribe to messages on particular topics. Itron uses a Java based enterprise called HiveMQ.

To learn more about MQTT in the context of Itron products and solutions, see MQTT Overview and MQTT API and Client Integration documentation.

MQTT Subscription Flow

 

 

Application APIs

 

SLV APIs

 

The Streetlight.Vision (SLV) CMS provides smart city and smart outdoor lighting projects with energy and maintenance savings while enhancing lighting service quality and safety in the street. SLV has a full suite of RESTful APIs for managing accounts, devices, measurements, and other entities within the application.

 

SLV Architecture-2020.png

 

The APIs can be used for:

  • Data integration
  • Real-time control
  • Scheduling
  • Configuration
  • Alarms & Reporting
  • Work Order Management

 

Get more details from the SLV API Documentation.

Embedded Device APIs

 

Milli Integrated Sensor API (SAPI)

 

Sensors are integrated with the Milli communications module with CoAP typically running on an application processor (micro controller). The interface to Milli is standard CoAP. The integration can implement this standard CoAP, however this does require you as a developer to learn and understand the CoAP specification. To simplify sensor implementations for our partners we provide an easy to understand and use API that abstracts you from the need to understand CoAP. This API is called Sensor API or SAPI for short.

Sensor API (SAPI) provides an easy way to add sensors to an HDK (or any Milli-based project using the CoAP Server). Composed of a set of API calls that have been added to the Itron Reference CoAP Server, SAPI frees the developer from needing to know anything about CoAP.

SAPI is packaged for release as a standard application with Atmel Studio as the IDE for use on the following processor types:

  • Arduino Metro
  • STM32
  • SAML21
  • SAML10
  • SAMD21

 SAPI is composed of two parts:

sapi_mshield: a replacement for the classic sensor code (mshield)

itron_coap_server: a new CoAP Server library

 

SAPI Features

Sensor API makes it easy to enable the following features for your sensor:

  • Provide a response to a sensor CoAP GET request

  • Provide a respsone to a configuration CoAP GET request

  • Handle a configuration request PUT request to change a sensor's configuration

  • Generate periodic observation notifications to upstream systems

  • Generate ad-hoc observation notifications to upstream systems

 

Learn more about SAPI and how to download it Sensor API Overview.