NAV
Neurio API
Resources

Overview

API Endpoint:

https://api.neur.io/v1/

The Neurio API allows developers to interface with data and services provided by the Neurio platform.

The current version of the API is v1, and can be accessed via the API endpoint.

Status

Definition:

GET https://api.neur.io/v1/status

Sample Request:

curl -i -X GET \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/status'

Sample Response: 200 OK

"1.16.6+build.1539"

The status of the API can be accessed via the status endpoint.

Authentication

The Neurio API uses the OAuth 2.0 protocol to authorize calls. To authenticate with the API, the first step you’ll need to do is register your application to obtain a client_ID and client_secret.

Once you have received your client credentials, you will be able to use these in your application to obtain an OAuth2 Bearer token, which may then be used by either personal data applications or 3rd-party applications to make any subsequent requests. For details on token generation and the OAuth 2.0 process flow, please refer to the OAuth 2.0 section.

Media Types

This API currently only outputs data in the JSON format. Specifying anything other than application/json in the Accept header will result in an error.

Sample Error Response:

{
  "code" : "invalid_entity",
  "message" : "Validation Failed",
  "errors" : [
    {
      "code" : "invalid_entity_name",
      "field" : "name",
      "message" : "First name cannot have fancy characters"
    },
    {
      "code" : "invalid_entity_password",
      "field" : "password",
      "message" : "Password cannot be blank"
    }
  ]
}

Errors

The common HTTP Response Status Codes are used to signify errors. Additionally, an error object is also sent in the body of the response:

Appliance Names

The following is a list of all the supported appliance name constants:

air_conditioner, dryer, electric_kettle, heater, microwave, other, oven, refrigerator, stove, toaster, unidentified

Conventions

Timestamps

All timestamps are returned in the ISO 8601 format:

yyyy-mm-ddThh:mm:ss.SSSZ

Pagination

(coming soon)

Rate Limiting

For requests requiring authorization via OAuth 2.0, you can make up to 144 requests per hour. For requests that do not require authorization, the rate limit allows you to make up to 120 requests per hour. You can check the returned HTTP headers of any API request to see your current rate limit status:

RateLimit-Limit: 144 RateLimit-Remaining: 100 RateLimit-Reset: 3094412

The headers tell you everything you need to know about your current rate limit status:

Header Name Description
RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour
RateLimit-Remaining The number of requests remaining in the current rate limit window
RateLimit-Reset The time at which the current rate limit window resets in milliseconds

Changelog

August 13, 2015

August 6, 2015

July 14, 2015

July 13, 2015

June 4, 2015

 

OAuth 2.0

The Neurio API supports the OAuth 2.0 Protocol. This allows external applications to request authorized access to a Neurio user’s safe private data without having to touch their user credentials.

Upon authorization by the user, an OAuth2 Bearer token can be generated by the API using your application’s client_ID and client_secret, in one of two ways:

For 3rd-party applications, once your users authenticate with Neurio your application will receive the token and be able to make API requests on their behalf via redirect URI.

For accessing your personal sensor data only, the forementioned redirect URI is not necessary and you can simply supply your client_id and client_secret to the Neurio server for an authentication token.

Redirect for authorization

Load this URI in a web browser session or a web view within a mobile app.

Definition:

https://api.neur.io/v1/oauth2/authorize{?client_id,redirect_uri,response_type}

Sample Redirect URI:

https://api.neur.io/v1/oauth2/authorize?response_type=code&client_id=BVlMq9azS7abZyq2wc1gnA&redirect_uri=https://testapp.com&state=mystate

Sample Returned URI:

https://testapp.com?code=ABC123&state=mystate

The user would then see a screen asking them to authorize your application. Once they grant permission, Neurio will redirect to the URI you specified earlier with a code parameter and the state parameter you provided.

The authorization code can then be used to get an access token.

Parameter Description
client_id (string) The client ID issued to the app
redirect_uri (string) The URI the user should be redirected to when successfully authenticated. The scheme, host and port of this URI must exactly match the callback URI specified during application registration, but it may also reference a subdirectory of the callback URI.
response_type (string) Value must be “code”
state (string) An arbitrary string of your choosing that will be included in the response to your application. We strongly recommends that you include an anti-forgery token here, and confirm it in the response to prevent CSRF attacks to your users.

Get access token

Definition:

POST https://api.neur.io/v1/oauth2/token

Sample Request:

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d \
'grant_type=authorization_code&client_id=BVlMq9azS7abZyq2wc1gnA&client_secret=XXXXrrXXXXzZZZoZZZZ&redirect_uri=https://testapp.com&state=mystate&code=ABC123' \
 'https://api.neur.io/v1/oauth2/token'

// NOTE: IF ONLY ACCESSING PERSONAL DATA, BODY CAN BE: //

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d \
'grant_type=client_credentials&client_id=BVlMq9azS7abZyq2wc1gnA&client_secret=XXXXrrXXXXzZZZoZZZZ' \
 'https://api.neur.io/v1/oauth2/token'

Sample Response: 200 OK

{
    "access_token": "AIOO-2n5gB2GPzTCKyn...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "created_at": "2014-04-21T22:28:32Z"
}

Allows a registered application to obtain an OAuth 2 Access Token. This endpoint can be used as follows:

1) For 3rd-party applications
Follow the first curl example by specifying the grant_type and supplying a redirect URI, state and response_type in addition to client_ID and client_secret

2) For accessing your personal sensor data only
Follow the second curl example by specifying the grant_type in addition to client_ID and client_secret

Parameter Description
grant_type (string) Use authorization_code for 3rd-party apps and client_credentials for accessing personal data
client_id (string) The client ID issued to the app
client_secret (string) The client secret issued to the app
redirect_uri (string, 3rd-party app use) The URI the user should be redirected to when successfully authenticated.
state (string, 3rd-party app use) An arbitrary string of your choosing that will be included in the response to your application.
code (string, 3rd-party app use) Code from your application.

Appliances

Appliances are electronic devices that have been added (labeled) to a location. Appliance object properties are:

Query by location

Definition:

GET https://api.neur.io/v1/appliances{?locationId}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances?locationId=0qX7nB-8Ry2bxIMTK0EmXw'

Sample Response: 200 OK

[
    {
        "id" : "2SMROBfiTA6huhV7Drrm1g",
        "createdAt" : "2014-04-21T22:28:32Z",
        "updatedAt" : "2014-04-21T22:45:32Z",
        "name" : "television",
        "label" : "upstairs TV",
        "tags" : ["bedroom_television", "42 inch LED"],
        "attributes" : {"autoDisagg": true},
        "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
    }
    ...
]

Other Responses: 404 ERROR

Get the appliances added for a specified location.

Parameter Description
locationId (string) Location ID for the place where sensor is installed

Get an appliance

Definition:

GET https://api.neur.io/v1/appliances/{id}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances/2SMROBfiTA6huhV7Drrm1g'

Sample Response: 200 OK

{
    "name" : "television",
    "label" : "upstairs TV",
    "tags" : ["bedroom_television", "42 inch LED"],
    "attributes" : {"autoDisagg": true},
    "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw",
    "createdAt" : "2014-04-21T22:28:32Z",
    "updatedAt" : "2014-04-21T22:45:32Z",
    "id" : "2SMROBfiTA6huhV7Drrm1g"
}

Other Responses: 404 ERROR

Get the information for a given appliance.

Parameter Description
id (string) ID of the Appliance

Appliance Analytics

For all appliance analytics endpoints, the following applies:

Query stats by location

Definition:

GET https://api.neur.io/v1/appliances/stats{?locationId,start,end,granularity,minPower,perPage,page,timezone, excludedType}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances/stats?locationId=0qX7nB-8Ry2bxIMTK0EmXw&start=2015-01-04T23:42:54.009Z&end=2015-01-30T19:19:10.278Z&granularity=days&minPower=400&perPage=5&page=2&timezone=America/Vancouver&excludedType=oven'

Sample Response: 200 OK

[
    {
        "appliance": {
            "label": "",
            "name": "dryer",
            "locationId": "0qX7nB-8Ry2bxIMTK0EmXw",
            "tags": [],
            "createdAt": "2015-01-04T23:42:54.009Z",
            "updatedAt": "2015-01-30T19:19:10.278Z",
            "id": "4SmROBfiTA6huhV7Drrm1h"
        },
        "averagePower": 5162.4,
        "eventCount": 5,
        "lastEvent": {
            "appliance": {
                "label": "",
                "name": "dryer",
                "locationId": "0qX7nB-8Ry2bxIMTK0EmXw",
                "tags": [],
                "createdAt": "2015-01-04T23:42:54.009Z",
                "updatedAt": "2015-01-30T19:19:10.278Z",
                "id": "4SmROBfiTA6huhV7Drrm1h"
            },
            "status": "complete",
            "start": "2015-02-04T22:24:41.816Z",
            "end": "2015-02-04T22:31:06.792Z",
            "energy": 1308604,
            "averagePower": 5155,
            "guesses": {
                "air_conditioner": 0.5,
                "dryer": 0.5
            },
            "groupIds": ["2pMROafiTA6huhV7Drrm1g"],
            "lastCycle": {
                "groupId": "cd0r-kOrRvWFbIuuUnL5GQ",
                "start": "2015-02-04T22:29:25.798Z",
                "end": "2015-02-04T22:31:06.792Z",
                "energy": 482612,
                "averagePower": 5182,
                "createdAt": "2015-02-04T22:29:38.701Z",
                "updatedAt": "2015-02-04T23:28:08.014Z",
                "significant": true,
                "sensorId": "0x0000C47F510179FE",
                "id": "Xj_L10ryTgSdX8euqj_fHw"
            },
            "cycleCount": 2,
            "isConfirmed": true,
            "id": "-yvnL0vgTN2DUx2dVv4uTw"
        },
        "timeOn": 687944,
        "energy": 14443276,
        "usagePercentage": 16.34809,
        "guesses": {},
        "start": "2015-02-04T03:37:51.566Z",
        "end": "2015-02-11T23:41:06.554Z",
        "groupIds": ["2pMROafiTA6huhV7Drrm1g"],
        "id": "Y8StKV6nStaXaguxnmNKtg"
    },
    ...
]

Other Responses: 404 ERROR

Get appliance usage data for a given location within a given time range. Stats are generated by fetching appliance events that match the supplied criteria and then aggregating them together based on the granularity specified with the request.

Parameter Description
locationId (string) ID of the location
start (string) start time for getting the stats of appliances
end (string) end time for getting the stats of appliances. Cannot be larger than 1 month from start time.
granularity = days (optional, string) granularity of stats. If the granularity is ‘unknown’, the stats for the appliances between the start and end time is returned. Values: days, weeks, months, unknown
minPower = 400 (optional, string) The minimum average power (in watts) for filtering. Only events with an average power above this value will be returned.
perPage = 10 (optional, string) the number of returned results per page (min 1, max 500)
page = 1 (optional, string) the page number to return (min 1, max 100000)
timezone = UTC (optional, string) the timezone name to let the api know how to handle daylight savings time
excludedType (optional, string) the type of the appliance to be excluded

Query stats by appliance

Definition:

GET https://api.neur.io/v1/appliances/stats{?applianceId,start,end,granularity,minPower,perPage,page,timezone}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances/stats?applianceId=4SmROBfiTA6huhV7Drrm1h&start=2015-01-04T23:42:54.009Z&end=2015-01-30T19:19:10.278Z&granularity=days&minPower=400&perPage=5&page=2&timezone=America/Vancouver'

Sample Response: 200 OK

[
    {
        "appliance": {
            "label": "",
            "name": "dryer",
            "locationId": "0qX7nB-8Ry2bxIMTK0EmXw",
            "tags": [],
            "createdAt": "2015-01-04T23:42:54.009Z",
            "updatedAt": "2015-01-30T19:19:10.278Z",
            "id": "4SmROBfiTA6huhV7Drrm1h"
        },
        "averagePower": 5162.4,
        "eventCount": 5,
        "lastEvent": {
            "appliance": {
                "label": "",
                "name": "dryer",
                "locationId": "0qX7nB-8Ry2bxIMTK0EmXw",
                "tags": [],
                "createdAt": "2015-01-04T23:42:54.009Z",
                "updatedAt": "2015-01-30T19:19:10.278Z",
                "id": "4SmROBfiTA6huhV7Drrm1h"
            },
            "status": "complete",
            "start": "2015-02-04T22:24:41.816Z",
            "end": "2015-02-04T22:31:06.792Z",
            "energy": 1308604,
            "averagePower": 5155,
            "guesses": {
                "air_conditioner": 0.5,
                "dryer": 0.5
            },
            "groupIds": ["2pMROafiTA6huhV7Drrm1g"],
            "lastCycle": {
                "groupId": "cd0r-kOrRvWFbIuuUnL5GQ",
                "start": "2015-02-04T22:29:25.798Z",
                "end": "2015-02-04T22:31:06.792Z",
                "energy": 482612,
                "averagePower": 5182,
                "createdAt": "2015-02-04T22:29:38.701Z",
                "updatedAt": "2015-02-04T23:28:08.014Z",
                "significant": true,
                "sensorId": "0x0000C47F510179FE",
                "id": "Xj_L10ryTgSdX8euqj_fHw"
            },
            "cycleCount": 2,
            "isConfirmed": true,
            "id": "-yvnL0vgTN2DUx2dVv4uTw"
        },
        "timeOn": 687944,
        "energy": 14443276,
        "usagePercentage": 16.34809,
        "guesses": {},
        "start": "2015-02-04T03:37:51.566Z",
        "end": "2015-02-11T23:41:06.554Z",
        "groupIds": ["2pMROafiTA6huhV7Drrm1g"],
        "id": "Y8StKV6nStaXaguxnmNKtg"
    },
    ...
]

Other Responses: 404 ERROR

Get appliance usage data for a single appliance within a given time range. Stats are generated by fetching appliance events that match the supplied criteria and then aggregating them together based on the granularity specified with the request.

Parameter Description
applianceId (string) ID of the appliance
start (string) start time for getting the stats of appliances
end (string) end time for getting the stats of appliances. Cannot be larger than 1 month from start time.
granularity = days (optional, string) granularity of stats. If the granularity is 'unknown’, the stats for the appliances between the start and end time is returned. Values: days, weeks, months, unknown
minPower = 400 (optional, string) The minimum average power (in watts) for filtering. Only events with an average power above this value will be returned.
perPage = 10 (optional, string) the number of returned results per page (min 1, max 500)
page = 1 (optional, string) the page number to return (min 1, max 100000)
timezone = UTC (optional, string) the timezone name to let the api know how to handle daylight savings time

Appliance Events

Appliance Events capture the instances in time when an appliance was used. For all appliance events endpoints, the following applies:

An appliance event can be in one of three states, as indicated by the status property:

Query by location

Definition:

GET https://api.neur.io/v1/appliances/events{?locationId,start,end,minPower,perPage,page}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances/events?locationId=0qX7nB-8Ry2bxIMTK0EmXw&start=2014-04-21T05:26:10.785Z&end=2014-04-21T05:36:00.547Z&minPower=500&perPage=5&page=2'

Sample Response: 200 OK

[
    {
        "id" : "1cRsH7KQTeONMzjSuRJ2aw",
        "appliance" : {
            "id" : "2SMROBfiTA6huhV7Drrm1g",
            "name" : "television",
            "label" : "upstairs TV",
            "tags" : ["bedroom_television", "42 inch LED"],
            "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
        },
        "start" : "2014-04-21T05:26:10.785Z",
        "end" : "2014-04-21T05:36:00.547Z",
        "guesses" : {"dryer1" : 0.78, "dishwasher_2014" : 0.12},
        "energy" : 247896,
        "averagePower" : 122,
        "groupIds" : [ "2pMROafiTA6huhV7Drrm1g", "4SmROBfiTA6huhV7Drrm1h" ],
        "lastCycle": {
            "groupId" : "4SmROBfiTA6huhV7Drrm1h",
            "start" : "2014-04-21T05:29:00.547Z",
            "end" : "2014-04-21T05:36:00.147Z",
            "energy" : 41846,
            "averagePower" : 122,
            "createdAt" : "2014-04-21T05:29:02.547Z",
            "updatedAt" : "2014-04-21T05:36:05.147Z",
            "sensorId" : "0x0013A00000000000",
            "id" : "ALJGM7voQpux5fujXtM2Qw"
        },
        "cycleCount" : 5,
        "status" : "complete",
        "isConfirmed" : false,
        "precedingEventId": "1cRsH7KQTeONMzjSuRJ2er"
    },
    ...
]

Other Responses: 404 ERROR

Get appliance events by location Id.

Parameter Description
locationId (string) ID of the location.
start (string) start time for getting the events of appliances.
end (string) end time for getting the events of appliances. Cannot be larger than 1 day from start time
minPower = 400 (optional, string) The minimum average power (in watts) for filtering. Only events with an average power above this value will be returned
perPage = 10 (optional, string) the number of returned results per page
page = 1 (optional, string) the page number to return

Query recent by location

Definition:

GET https://api.neur.io/v1/appliances/events{?locationId,since,minPower,perPage,page}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://v1/appliances/events?locationId=0qX7nB-8Ry2bxIMTK0EmXw&since=2014-04-21T05:26:10.785Z&minPower=100&perPage=5&page=2'

Sample Response: 200 OK

[
    {
        "id" : "1cRsH7KQTeONMzjSuRJ2aw",
        "appliance" : {
            "id" : "2SMROBfiTA6huhV7Drrm1g",
            "name" : "television",
            "label" : "upstairs TV",
            "tags" : ["bedroom_television", "42 inch LED"],
            "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
        },
        "start" : "2014-04-21T05:26:10.785Z",
        "end" : "2014-04-21T05:36:00.547Z",
        "guesses" : {"dryer1" : 0.78, "dishwasher_2014" : 0.12},
        "energy" : 247896,
        "averagePower" : 122,
        "groupIds" : [ "2pMROafiTA6huhV7Drrm1g", "4SmROBfiTA6huhV7Drrm1h" ],
        "lastCycle": {
            "groupId" : "4SmROBfiTA6huhV7Drrm1h",
            "start" : "2014-04-21T05:29:00.547Z",
            "end" : "2014-04-21T05:36:00.147Z",
            "energy" : 41846,
            "averagePower" : 122,
            "createdAt" : "2014-04-21T05:29:02.547Z",
            "updatedAt" : "2014-04-21T05:36:05.147Z",
            "sensorId" : "0x0013A00000000000",
            "id" : "ALJGM7voQpux5fujXtM2Qw"
        },
        "cycleCount" : 5,
        "status" : "complete",
        "isConfirmed" : false,
        "precedingEventId": "1cRsH7KQTeONMzjSuRJ2er"
    },
    ...
]

Other Responses: 404 ERROR

Get appliance events created or updated after a specific time.

Parameter Description
locationId (string) ID of the location
since (string) the time for getting events that are created or updated after it. Maximum value allowed is 1 day from the current time.
minPower = 400 (optional, string) The minimum average power (in watts) for filtering. Only events with an average power above this value will be returned
perPage = 10 (optional, string) the number of returned results per page
page = 1 (optional, string) the page number to return

Query by appliance

Definition:

GET https://api.neur.io/v1/appliances/events{?applianceId,start,end,minPower,perPage,page}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/appliances/events?applianceId=2SMROBfiTA6huhV7Drrm1g&start=2014-04-21T05:26:10.785Z&end=2014-04-21T05:36:00.547Z&minPower=100&perPage=5&page=2'

Sample Response: 200 OK

[
    {
        "id" : "1cRsH7KQTeONMzjSuRJ2aw",
        "appliance" : {
            "id" : "2SMROBfiTA6huhV7Drrm1g",
            "name" : "television",
            "label" : "upstairs TV",
            "tags" : ["bedroom_television", "42 inch LED"],
            "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
        },
        "start" : "2014-04-21T05:26:10.785Z",
        "end" : "2014-04-21T05:36:00.547Z",
        "guesses" : {"dryer1" : 0.78, "dishwasher_2014" : 0.12},
        "energy" : 247896,
        "averagePower" : 122,
        "groupIds" : [ "2pMROafiTA6huhV7Drrm1g", "4SmROBfiTA6huhV7Drrm1h" ],
        "lastCycle": {
            "groupId" : "4SmROBfiTA6huhV7Drrm1h",
            "start" : "2014-04-21T05:29:00.547Z",
            "end" : "2014-04-21T05:36:00.147Z",
            "energy" : 41846,
            "averagePower" : 122,
            "createdAt" : "2014-04-21T05:29:02.547Z",
            "updatedAt" : "2014-04-21T05:36:05.147Z",
            "sensorId" : "0x0013A00000000000",
            "id" : "ALJGM7voQpux5fujXtM2Qw"
        },
        "cycleCount" : 5,
        "status" : "complete",
        "isConfirmed" : false,
        "precedingEventId": "1cRsH7KQTeONMzjSuRJ2er"
    },
    ...
]

Other Responses: 404 ERROR

Get appliance events by appliance Id.

Parameter Description
applianceId (string) ID of an appliance.
start (string) start time for getting the events of appliances.
end (string) end time for getting the events of appliances. Cannot be larger than 1 day from start time
minPower = 400 (optional, string) The minimum average power (in watts) for filtering. Only events with an average power above this value will be returned
perPage = 10 (optional, string) the number of returned results per page
page = 1 (optional, string) the page number to return







Samples

Samples contain information on power and energy consumption registered by a sensor. For all samples endpoints, the following applies:

Query recent samples

Definition:

GET https://api.neur.io/v1/samples/live{?sensorId,last}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/samples/live?sensorId=0xoooo0000oooo0000&last=2014-03-21T20:28:32Z'

Sample Response: 200 OK

[
    {
        "consumptionPower": 120,
        "consumptionEnergy" : 17,
        "generationPower" : 14,
        "generationEnergy" : 2,
        "netPower": 106,
        "netEnergy": 15,
        "submeters": [
            {
                "power": 10,
                "energy": 4,
                "name": "dryer-submeter",
                "channelNumber": 4
            },
            ...
        ],
        "timestamp": "2014-03-21T20:28:32Z"
    },
    ...
]

Get recent samples, one sample per second for up to the last 2 minutes.

Parameter Description
sensorId (string) sensor ID
last (optional, timestamp) time of last sample received, defaults to 2 minutes ago if omitted

Get last sample

Definition:

GET https://api.neur.io/v1/samples/live/last{?sensorId}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/samples/live/last?sensorId=0xoooo0000oooo0000'

Sample Response: 200 OK

{
    "consumptionPower": 120,
    "consumptionEnergy": 17,
    "generationPower": 14,
    "generationEnergy": 2,
    "netPower": 106,
    "netEnergy": 15,
    "submeters": [
        {
            "power": 10,
            "energy": 4,
            "name": "dryer-submeter",
            "channelNumber": 4
        },
        ...
    ],
    "timestamp": "2014-03-21T20:28:32Z"
}

Get the last sample recorded by the sensor.

Parameter Description
sensorId (string) sensor ID

Query history samples

Definition:

GET https://api.neur.io/v1/samples{?sensorId,start,end,granularity,frequency,perPage,page}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/samples?sensorId=0xoooo0000oooo0000&start=2014-03-21T20:28:32Z&end=2014-03-21T20:50:32Z&granularity=minutes&frequency=5&perPage=5&page=2'

Sample Response: 200 OK

[
    {
        "consumptionPower": 120,
        "consumptionEnergy": 17,
        "generationPower": 14,
        "generationEnergy": 2,
        "netPower": 106,
        "netEnergy": 15,
        "submeters": [
            {
                "power": 10,
                "energy": 4,
                "name": "dryer-submeter",
                "channelNumber": 4
            },
            ...
        ],
        "timestamp": "2014-03-21T20:28:32Z"
    },
    ...
]

Sample Response: 400, 404 ERROR

{
    "status": 400,
    "code": "invalid_request",
    "message": "Your request could not be processed. See 'errors' property for more details.",
    "errors": [
        {
            "code": "invalid_request",
            "field": "end",
            "resource": "",
            "message": "Maximum time range for 'minutes' granularity is 1 day."
        },...
    ]
}

Get a sensor’s samples for a specified time interval.

Parameter Description
sensorId (string) sensor ID
start (string) start timestamp of sampling; depending on the granularity parameter value, the maximum supported time range is: 1 day for minutes, 31 days for hours, 92 days for days, 6 months for weeks, 1 year for months, and 10 years for years granularities
end (optional, string) (the current time) end timestamp of sampling, should be later than start time
granularity (string) granularity of the sampled data. Values: minutes, hours, days, weeks, months, years
frequency = 1 (optional, string) frequency of the sampled data (e.g. with granularity set to days, a value of 3 here will result in a sample for every third day, should be a multiple of 5 when using minutes granularity)
perPage = 10 (optional, string) the number of returned results per page (min 1, max 500)
page = 1 (optional, string) the page number to return (min 1, max 100000)

Query energy stats

Definition:

GET https://api.neur.io/v1/samples/stats{?sensorId,start,end,granularity,frequency,timezone}

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/samples/stats?sensorId=0xoooo0000oooo0000&start=2014-03-21T20:28:32Z&end=2014-03-21T20:50:32Z&granularity=minutes&frequency=5&timezone=America/Vancouver'

Sample Response: 200 OK

[
    {
        "consumptionEnergy" : "2.568036E7",
        "generationEnergy" : "1.468036E7",
        "importedEnergy": 123456,
        "exportedEnergy": 456789,
        "submeters":[
            {
                "energy": 437,
                "name": "dryer-submeter", 
                "channelNumber": 4
            },
            ...
        ],
        "start" : "2014-03-21T20:50:32-07:00",
        "end" : "2014-03-21T20:50:32-07:00"
    }
    ...
]

Sample Response: 400, 404 ERROR

{
    "status": 400,
    "code": "invalid_request",
    "message": "Your request could not be processed. See 'errors' property for more details.",
    "errors": [
        {
            "code": "invalid_request",
            "field": "granularity",
            "resource": "",
            "message": "Valid granularity values are: years, weeks, time-of-use, unknown, minutes, hours, months, days."
        }
    ]
}

Get brief stats for energy consumed in a given time interval.

Parameter Description
sensorId (string) sensor ID
start (string) start timestamp of sampling; depending on the granularity parameter value, the maximum supported time range is: 1 day for minutes, 31 days for hours, 92 days for days, 6 months for weeks, 1 year for months, 10 years for years, and 32 days for time-of-use granularities
end (optional, string) (the current time) end timestamp of sampling
granularity (string) granularity of the sampled data. Values: minutes, hours, days, weeks, months, years, unknown, time-of-use
frequency = 1 (optional, string) frequency of the sampled data (NOTE: if the granularity specified is ‘minutes’, the frequency must be a multiple of 5 (e.g. 5, 10, 15 …))
timezone = UTC (optional, string) the timezone name to let the api to know how to handle daylight savings time

Sensor Local Access

The Neurio Sensor implements a JSON format sensor value output. By calling http://<IP_address>/current-sample the sensor returns latest measurement value of mime type.

Definition:

GET http://<IP_address>/current-sample

Sample Request:

curl -i -X GET \
   -H "Content-Type:application/json" \
 'http://255.255.255.255/current-sample'

Sample Response: 200 OK

{
    "sensorId": "0xoooo0000oooo0000",
    "timestamp": "2014-03-21T20:28:32Z",
    "channels": [
        {
            "type": "PHASE_A_CONSUMPTION",
            "ch": 1,
            "eImp_Ws": 0,
            "eExp_Ws": 0,
            "p_W": 0,
            "q_VAR": 0,
            "V_V": 0.160
        },
         
    ],
    "cts": [ 
        {
            "ct": 1,
            "p_W": -300,
            "q_VAR": -24,
            "v_V": 0.16
        },
        
    ]
}

For “channels” the following applies:

For “cts” the following applies:







Users

Get the current user

Definition:

GET https://api.neur.io/v1/users/current

Sample Request:

curl -i -X GET \
   -H "Authorization:Bearer AIOO-2nk22GF...NN2jo" \
   -H "Content-Type:application/json" \
 'https://api.neur.io/v1/users/current'

Sample Response: 200 OK

{
    "id": sp94LQOykAMgkAyJye,
    "name" : "Bruce Bane",
    "email" : "bruce@bane.com",
    "status" : "active",
    "createdAt" : "2014-04-21T22:28:32Z",
    "updatedAt" : "2014-04-21T22:45:32Z",
    "locations" : [
        {
            "id" : "2SMROBfiTA6huhV7Drrm1g",
            "name" : "my home",
            "timezone" : "America/Vancouver",
            "sensors" : [
                {
                    "id" : "0x0000000000000001",
                    "sensorId": "0x0000000000000001",
                    "name" : "sensor 1",
                    "sensorType" : "powerblaster",
                    "platformType" : "pro",
                    "channels" : [
                        {
                            "channel" : 1,
                            "channelType" : "phase_a"
                        },
                        ...
                    ]
                },
                ...
            ],
            "billingType": "tiered",
            "energyRate": 0.1,
            "billingCycleDay" : 1,
            "budget": 100.00,
            "pricingTiers" : [
                {
                    "minConsumption": 0, 
                    "maxConsumption": 300, 
                    "price": 0.012
                },
                {
                    "minConsumption": 300, 
                    "maxConsumption": 700, 
                    "price": 0.011
                },
                {
                    "minConsumption": 700, 
                    "price": 0.01
                }
            ],
            "fixedCharge" : 100.99,
            "taxRate" : 12.89,
            "postalCode": "V1V 1V1",
            "homeType": "house",
            "homeSize": 2000,
            "residents": 3,
            "rank": {
                "locationId": "2SMROBfiTA6huhV7Drrrmg",
                "category": {
                    "description": "step 0: unspecified",
                    "code": 0,
                    "count": 66,
                    "metric": "always_on",
                    "percentiles": [
                        {
                            "percentage": 0,
                            "score": 2190
                        },
                        {
                            "percentage": 30,
                            "score": 272
                        },
                        {
                            "percentage": 70,
                            "score": 83
                        },
                        {
                            "percentage": 100,
                            "score": 1
                        }
                    ],
                    "createdAt": "2015-08-06T21:43:12.738Z",
                    "updatedAt": "2015-08-13T18:03:28.000Z",
                    "id": "-isdWxgEQA-FgUB5VHiqKg"
                },
                "percentile": {
                    "percentage": 75,
                    "score": 56
                },
                "createdAt": "2015-08-10T22:12:58.000Z",
                "updatedAt": "2015-08-13T18:03:28.000Z",
                "id": "f50478c6-3fac-11e5-a3a"
            },
            "alwaysOn": [
                {
                    "name": "target",
                    "score": 22,
                    "updatedAt": "2015-08-24T20:57:42.386Z"
                },
                {
                    "name": "average",
                    "score": 112.3,
                    "updatedAt": "2015-08-25T01:07:17.724Z"
                }
            ],
            "timeOfUsePricing": {
                "weekends": "excluded",
                "pricingPeriods": [
                    {
                        "start": 0,
                        "end": 10,
                        "price": 20,
                        "type": "offPeak"
                    },
                    {
                        "start": 10,
                        "end": 20,
                        "price": 10,
                        "type": "peak"
                    },
                    {
                        "start": 20,
                        "end": 24,
                        "price": 0,
                        "type": "peak"
                    }
                ]
            }
        },
        ...
    ],
    "releaseFeatures": [
        {
            "userId": "sp94LQOykAMgkAyJye",
            "releaseFeature": {
                "name": "ADAaccuracy",
                "description": "This feature collects user feedback about ADA accuracy",
                "createdAt": "2015-10-16T23:48:36.748Z",
                "id": "pnmE-vS8SdOKpJPARJR4zw"
            },
            "createdAt": "2015-10-17T00:32:20.349Z",
            "id": "kZHwJJQWSTahyIgmwGbY6g"
        },
        ...
    ]
}

Other Responses: 404 ERROR