Wattvision API

API version 0.1 is deprecated. Please upgrade to 0.2. This will be turned off on January 1, 2014.

Send Data to Wattvision

HTTP POST to: http://www.wattvision.com/api

h=123123
k=90232Dde3432334
v=0.1
watts=1230

Required Parameters:

hYour House ID. Available on the settings page. ("My House" > "Settings")
kYour Secret Key. Available on the settings page. ("My House" > "Settings")
vAPI Version. It's 0.1
wattsThe present consumption in watts (as a float).

Optional Parameters:

timeThe UTC timestamp for this data point, in exactly this format (ISO datetime): YYYY-MM-DDTHH:MM:SS. Note, this is not your local time, but UTC. When not submitted, the server timestamps the time, so network delays may an issue.
wh_consumedThe number (integer) of whole watt-hours consumed since the last data post. Partial watt-hours should be part of the next data point. If you do not include wh_consumed, we will estimate wh_consumed by 'integrating' watts x time.
ms_per_whInstead of 'watts', you may submit the present consumption rate in milliseconds per watt-hour (integer number). Rounded to the nearest millisecond.

Update Strategy

Post data as slow as once every 20 minutes, or as fast as every 15 seconds. We can accept data faster than every 15 seconds -- if you want to do that, email info@. Do not attempt to upload at exactly :00, :15, :45, etc -- instead, just set your timer to fire at a set period and start at an arbitrary time.

If you want to have your sensor showing as "sensor active" you must consistently upload faster than once every 5 minutes.

Response Codes

Right now, everything returns "HTTP 200 OK" with some explanatory text on error or 'data added' if it worked.

Download Data from Wattvision

Get the last 5 minutes of data:

HTTP GET: http://www.wattvision.com/api/download?h=HOUSE_ID&k=API_KEY&v=0.1

Required Parameters

hYour House ID. Available on the settings page. ("My House" > "Settings")
kYour Secret Key. Available on the settings page. ("My House" > "Settings")
vAPI Version. It's 0.1

Return Format

  • returns the last 5 minutes of data
  • returns a JSON array with the following format:
    • first item is an array [ house_name, 0, 0 ]
    • remaining items are arrays formatted as [ unix time, watts, cents ]
    • Cents is "cost in cents per hour"

Get the most recent datapoint:

HTTP GET: http://www.wattvision.com/api/download/latest?h=HOUSE_ID&k=API_KEY&v=0.1

Required Parameters

hYour House ID. Available on the settings page. ("My House" > "Settings")
kYour Secret Key. Available on the settings page. ("My House" > "Settings")
vAPI Version. It's 0.1

Return Format

  • returns the most recent data point from wattvision's servers
  • returns a JSON array with 3 items [ unix time, watts, cents ]
  • Cents is "cost in cents per hour"

API Version 0.2 is centered around sensors. You can store data with sensor ID, and you can download data given a sensor ID.

Send Data to Wattvision

HTTPS POST to URL: https://www.wattvision.com/api/v0.2/elec

The parameters are passed as part of the body of the POST request. We expect a JSON object with each of the following properties, some of which are optional. Note that JSON strings are enclosed by double quotes and numbers are not.

Examples

  • On the command line:
    curl -d '{"sensor_id":"XXXXXX","api_id":"XXXXXX","api_key":"XXXXXX","watts":1003}' http://www.wattvision.com/api/v0.2/elec

  • See some sample code here: Github API Sample Code

Parameters:

'sensor_id'(Required, JSON string) The sensor id with which the uploaded data will be associated. Must be authorized at the API Settings Page.
'api_id'(Required, JSON string) the api id that authorizes this data upload. Found on API Settings Page.
'api_key'(Required, JSON string) the api key that authorizes this data upload. Found on API Settings Page.
'time'(Optional, JSON string) the UTC ISO format date time (YYYY-MM-DDTHH:MM:SS) associated with the uploaded data, if not provided server time is used
You'll need to upload one or both of 'watts' or 'watthours'
'watts'(JSON number) a float value of a watts measurement
'watthours'(JSON number) a float value of the watthours consumed since the sensor started recording data (for a house that does not put energy back to the grid this number is a monotonically increasing function of time, but it doesn't have to be.)

Update Strategy

If you want to have your sensor showing as "sensor active" you must consistently upload faster than once every 5 minutes.

Response Codes

You will receive a 400 Bad Request if the request is not in the correct format.

Download Data from Wattvision

HTTPS GET:

https://www.wattvision.com/api/v0.2/elec?sensor_id=###&api_id=###&api_key=###&type=rate
&start_time=2013-01-18T21:50:00&end_time=2013-01-18T22:57:00

Parameters:

sensor_idThe sensor ID to get data from. Found on API Settings Page.
api_idThe API ID. Found on API Settings Page.
api_keyThe API KEY. Found on API Settings Page.
typerate returns watts or consumption returns watthours
start_timeISO UTC start time for data range
end_timeISO UTC end time for data range

Return Format

Returns a JSON object with two attributes:
  • "units" which is the units of the returned measurement.
  • "data" which is an array of JSON objects each with two attributes. "t" the time of the data point, and "v" the measurement