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
- Updated User endpoint samples with newly added location information,
rank
: the location’s ranking for home comparison
August 6, 2015
- Updated User endpoint samples with newly added location information, including:
budget
: the user’s budget for the billing cyclepostalCode
: the location’s postal codehomeType
: the location’s home type (house/apartment)homeSize
: the location’s size in square feetresidents
: number of people living at the location
July 14, 2015
- Updated User endpoint samples with new feature information, including:
billingCycleDay
: user’s billing cycle start day of the monthbillingType
: type of billing plan that user has selectedpricingTiers
: an array of the user’s energy prices based on tiers of energy usagefixedCharge
: user’s fixed utility charge per billing cycletaxRate
: user’s tax rate percentage per billing cycle
July 13, 2015
- OAuth 2.0 documentation revised for clarity
June 4, 2015
- Updated to match Neurio API v1. Resources currently available:
- OAuth 2.0 - API authentication support for external applications
- Samples - endpoints for retrieving sensor sample data
- Appliances - endpoints for retrieving appliance information
- Appliance Events - endpoints for retrieving appliance event data
- Appliance Analytics - endpoints for retrieving usage data
- Users - endpoint for retrieving user information
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:
name
: specifies the type of appliance, see section Appliance Names for supported values,locationId
: the ID of the location where the appliance is located,label
: optional, a custom label for the appliance (eg."Upstairs stove"
),tags
: optional, array of the appliance’s tags (eg.["Cooking", "Kitchen"]
),createdAt
: timestamp of when the appliance was first created (managed internally by the API, cannot be set with a request),updatedAt
: timestamp of when the appliance was last updated, empty if appliance was never updated (managed internally by the API, cannot be set with a request).
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:
- energy values are returned in watt-seconds,
- power values are returned in watts,
- when requesting results with
minutes
value for thegranularity
parameter, thefrequency
parameter should be a multiple of 5.
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:
- energy values are returned in watt-seconds,
- power values are returned in watts.
An appliance event can be in one of three states, as indicated by the status
property:
in_progress
- the appliance is currently runningcycled
- the appliance has just cycled and may cycle againcomplete
- the appliance has finished running
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:
- energy values are returned in watt-seconds,
- power values are returned in watts,
- when requesting results with
minutes
value for thegranularity
parameter, thefrequency
parameter should be a multiple of 5.
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
},
…
]
}
timestamp
: Represents the UTC date/time value when measurement was executed in ISO8601 format. In case of an unsynchronized sensor time, this value is set to “NOT_SYNCHRONIZED”.channels
: Array containing information for [up to] the six logical channels.cts
: An array of 4 CTs.
For “channels” the following applies:
type
: Channel type in string format. Possible values are: PHASE_A_CONSUMPTION, PHASE_B_CONSUMPTION, PHASE_C_CONSUMPTION, NET, GENERATION, CONSUMPTION, SUBMETER.ch
: Channel numbereImp_Ws
: Imported energy in watt-secondseExp_Ws
: Exported energy in watt-secondsp_W
: Real power in wattsq_VAR
: Reactive power in volt-amps reactivev_V
: Voltage in voltslabel
: User defined channel label. Only returned for SUBMETER type channels.
For “cts” the following applies:
ct
: CT enumerationp_W
: Real power in wattsq_Var
: Reactive power in volt-amps reactivev_V
: Voltage in volts
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