Helium Blog

The Helium API

Helium is a sensing platform that makes it simple to gather data and develop insights about your organization’s physical assets and environment. We offer a rich set of HTTP endpoints to make it easy for developers to manage and create solutions based on their installed Helium Smart Sensors.

Note: The previous v0 API is marked as deprecated. If you were relying on the v0 API please make plans to migrate to v1. The v0 API will be officially unsupported on October 1, 2016.

What’s new

The v1 API offers extensive, modern access to nearly all the resources available in Helium. These range from listing your sensors to managing labels of sensors and efficiently accessing sensor data. The full list of available endpoints is available in the API documentation. We also have an open-source command line tool, called helium-commander, available that shows how to use the API and is a useful way to explore your data.

Quick Start

In order to use the Helium API you will need an API key. If you have a Helium account already you can get your API key using the API using the user/auth endpoint. Here’s an example using the excellent httpie tool. Fill in your and .

http POST [https://api.helium.com/v1/user/auth](https://api.helium.com/v1/user/auth)  email=<user> password=<password>

If successful this will return a JSON object that will include the api-token for the given user.

{  
    "data": {  
        "attributes": {  
            "name": "Jane Developer"  
        },  
        "id": "developer@helium.com",  
        "meta": {  
            "api-token": "8abnUdPP0HZC6lqQfkjhsdfkh298as/btN98=",  
            "email": "developer@helium.com"  
        },  
        "type": "user"  
    }  
}

Use this token as authorization for any requests you make to Helium. The easiest was to do this is to set the token as an environment variable:

export HELIUM_API_KEY=your api token>

You can now use this environment variable to make subsequent requests to the API. For example, to get a list of the sensors your organization owns:

http GET [https://api.helium.com/v1/sensor](https://api.helium.com/v1/sensor) Authorization:$HELIUM_API_KEY

Which should return a list of sensors that looks somewhat like this:

{  
    "data": [  
        {  
            "attributes": {  
                "name": "Freezer Internal"  
            },  
            "id": "b427abef-ef0e-4429-9128-b919faea0bd4",  
            "meta": {  
                "created": "2016-02-24T21:17:20.619754Z",  
                "mac": "6081f9fffe0007a4",  
                "ports": [  
                    "b",  
                    "d",  
                    "t"  
                ],  
                "updated": "2016-02-24T21:17:20.618869Z"  
            },  
            "type": "sensor"  
        },  
        {  
            "attributes": {  
                "name": "Marc's Desk"  
            },  
            "id": "08bab58b-d095-4c7c-912c-1f8024d91d95",  
            "meta": {  
                "created": "2015-08-06T17:28:11.614107Z",  
                "mac": "6081f9fffe00019b",  
                "ports": [  
                    "b",  
                    "t"  
                ],  
                "updated": "2016-04-21T03:52:30.959109Z"  
            },  
            "type": "sensor"  
        }  
    ]  
}

See the API documentation for a full list of all the resources you can address and what kind of requests you can make to them. That covers the basics! Hopefully that was pretty easy to follow. If you have any questions, leave a comment or contact us at hello@helium.com Read on for more details on some of the key concepts behind the API.

Concepts

The Helium API uses json:api as its primary structure. JSONAPI offers a consistent way to encode resources and their relationships for clients to consume. The key parts of JSONAPI are:

  • Resources — Which represent JSON objects that have a type and an id.
  • Attributes — A resource object can have zero or more attributes which are associated with the given resource.
  • Relationships — A resource can have relationships with other resources. These relationships are encoded in a relationships section and include the id and type of the related resource.
  • Paging — Some resources, such as timeseries data, are returned in a paged form. Paged data include a links section with prev and next links to fetch older and newer data respectively.

See the JSONAPI documentation for more details on the exact JSON format for each of these.

We’ll cover each of the Helium specific resources next.

Sensors

Sensors form the primary source of data that comes from the physical world. In Helium, sensors can take one of two forms:

  • physical, which means it’s an actual device like a Helium sensor.
  • virtual which is an addressable resource but some other application is supplying data through the API.

Sensors produce timeseries data for each of the physical readings they produce. These readings can be based on physical events like a door opening or closing or a temperature being sampled on a regular basis. Readings can also be virtual, like a script POSTing zipcode weather readings. Here’s an example of what a physical sensor resource, named “Fridge”, looks like:

{  
    "attributes": {  
        "name": "Fridge"  
    },  
    "id": "1256b833-a1b9-4977-98c0-e143d3a2c773",  
    "meta": {  
        "created": "2016-04-21T20:20:03.970568Z",  
        "mac": "6081f9fffe000748",  
        "ports": [  
            "d",  
            "t"  
        ],  
        "updated": "2016-04-21T20:20:03.97075Z"  
    },  
    "type": "sensor"  
}

Note the attributes describe the name of the sensor, which can be changed using the PATCH sensor/:id endpoint. The meta section describes when the resource was created and last patched, the device’s MAC address and the ports, or types of data, that the sensor is emitting.

Elements

Elements are the physical access points that allow Helium’s Smart Sensors to connect and communicate with the Helium platform. They’re pretty simple but they may have information available for querying that may be of interest to an application managing a physical group of sensors. Here’s an example of what an element resource looks like:

{  
    "attributes": {  
        "name": "Office"  
    },  
    "id": "d6c8d735-a419-4ed4-a431-9d87a096917f",  
    "meta": {  
        "created": "2015-08-12T22:38:30.230247Z",  
        "mac": "6081f9fffe0001ef",  
        "updated": "2016-03-10T19:53:12.408872Z"  
    },  
    "type": "element"  
}

Note the attributes describe the name of the element which can be changed using the PATCH element/:id endpoint. The meta section describes when the resource was created and the attributes last updated as well as the MAC address of the element.

Labels

Labels enable grouping of sensors. A sensor can belong to none, one, or many labels. The API exposes endpoints to create, list and manipulate membership of labels.

User

A user is someone that is using an API key to access Helium. Each user gets their own individual API key. The GET user/auth endpoint enables you to get an API key for a given user and password.A normal user resource looks like this:

{  
    "data": {  
        "attributes": {  
            "name": "Demo Account"  
        },  
        "id": "demo@helium.com",  
        "meta": {  
            "created": "2015-07-21T19:27:42.501309Z",  
            "email": "demo@helium.com",  
            "updated": "2015-07-29T21:45:59.745486Z"  
        },  
        "type": "user"  
    }  
}

Organization

An organization is the owner of all users, data and physical devices for a specific real world user of Helium, whether an individual or a company. All users in an organization can currently see all data and devices in the organization. The organization resource also offers up a timeseries endpoint to aggregate organization level data such as events and notifications. This way you don’t have to listen to every sensor for connection events, but can just look at the organization timeseries for events that pertain to sensors connecting.

Timeseries

Helium offers up timeseries endpoints for a number of resources, including sensors and the authenticated organization. Timeseries data is a JSONAPI resource of type data-point that has three attributes:

  • port — which can be seen as a tag or type of the reading. For example a port t indicates temperature (in Celsius), but a port p is pressure in Pascals. There are a number of well defined ports that Helium Smart Sensors produce but you can use any port name that makes sense for data that you produce or inject into the system.
  • value — The value of the reading. Any valid JSON value is allowed here. If the value happens to be a number the timeseries endpoint can do more complex aggregations on value for their port.
  • timestamp — The ISO8601 timestamp of when the reading was taken.

Timeseries data is returned using a cursor based paging mechanism and can be:

  • Filtered by one or more ports;
  • Constrained to given date range;
  • Aggregated using aggregation primitives like min, max and avg and buckets of various sizes.

See the timeseries documentation for details on the various request parameters. You can also inject timeseries data into any sensor, whether virtual or physical by doing an HTTP POST to the relevant timeseries endpoint using the above attributes for a data-point. Using this endpoint, we’re already starting to see partners integrate functionality that is delivering value to customers. Glowfish.io is a great example of this in the Machine Learning space. A sample data-point looks as follows:

{  
    "data": [  
        {  
            "attributes": {  
                "port": "t",  
                "timestamp": "2016-06-23T18:26:56.706Z",  
                "value": 26.258064  
            },  
            "id": "5bb1e7b2-5c6e-4fa7-8eeb-f6edea232d61",  
            "meta": {  
                "created": "2016-06-23T18:28:00.580578Z"  
            },  
            "relationships": {  
                "sensor": {  
                    "data": {  
                        "id": "62ea012e-34b1-4802-8463-513fae60ac47",  
                        "type": "sensor"  
                    }  
                }  
            },  
            "type": "data-point"  
        }  
    ],  
    "links": {  
        "prev": "https://api.helium.com/v1/sensor/62ea012e-34b1-4802-8463-513fae60ac47/timeseries?page%5Bid%5D=15c2c960-751b-4ee2-a7b0-745c96c51dea&page%5Bsize%5D=1"  
    }  
}

Metadata

All top level resources expose a metadata relationship. Metadata for a resource is an arbitrary JSON object. You can use an HTTP PATCH request to add attributes to the metadata of a resource or an HTTP PUT to replace the complete metadata object. A sample metadata object for a sensor looks as follows:

{  
    "data": {  
        "attributes": {  
            "location": {  
                "address": "720 West Monument Street",  
                "area": "1st floor"  
            }  
        },  
        "id": "05e0a940-e12f-46fd-9880-724c912f5eb7",  
        "type": "metadata"  
    }  
}

Conclusion

That completes a quick overview of the main concepts and structure of the Helium API. We use it extensively at Helium to build our own internal and external experiences and hope it’s as useful to others as it is to us! For complete documentation refer to the the Helium API documentation. To access the API from the command line and dive into code, check out helium-commander If you’re not using Helium but want to be, email hello@helium.com