Pulse API

version 1

The Pulse API provides access to live data from the Pulse™ Platform.

Important: Use of the API requires that you accept the API Terms of Use.

Topics:

Authentication

When you register an API application within Pulse, you are provided with a key. This key must accompany each API request in order to for it to be authenticated successfully.

There are two methods of including the key:

If a key is not provided, the request will be denied and you will get a response with status 403 (Forbidden).

Caution: Your API key must be kept secret. To prevent anyone from getting it and potentially accessing your data, only make server-side API requests that aren't visible to users of your application or website.

Root Url

The root url you use to access the API will depend on the country your data is stored in.

In Canada, the URL is https://api.ca.pulseenergy.com

In the United States, the URL is https://api.us.pulseenergy.com

The examples here are for the Canadian environment.

Rate Limit

The Pulse API allows a limited number of hourly requests to protect against potential abuse. For most applications, the limit is approximately 100 requests per hour.

If your application exceeds this limit, it will be temporarily disabled and further requests will get a response with status 420.

If this limit is too low for your needs, please contact us to request an increase.

Date Format

The API supports two date formats:

The date format of the request will determine the date format used in the response.

Important: Unix epoch is in seconds, not milliseconds.

Response Format

API responses are in either JSON or XML. You have two options for specifying which you prefer.

The first way is to include the format directly in the URL like a file extension, as in the following two examples:

» https://api.ca.pulseenergy.com/pulse/1/points/25393.json
{
    "id": 25393,
    "label": "Arilou Energy",
    "unit": "kWh",
    "type": "energy",
    "measurement": "electricity",
    "timezone": "America/Vancouver"
}
» https://api.ca.pulseenergy.com/pulse/1/points/25393.xml
<point>
    <id>25393</id>
    <label>Arilou Energy</label>
    <unit>kWh</unit>
    <type>energy</type>
    <measurement>electricity</measurement>
    <timezone>America/Vancouver</timezone>
</point>

Alternatively, you can omit the extension and set the "Accept" header of the request to include "application/json" or "application/xml": 

GET /pulse/1/points/25393 HTTP/1.1
Host: api.ca.pulseenergy.com
Accept: application/json

Tip: For JSONP calls, you can include a callback parameter.

https://api.ca.pulseenergy.com/pulse/1/points/25393.json?callback=myFunction:

myFunction(
  {
    "id": 25393,
    ...
    "timezone": "America/Vancouver"
  }
)

Resources

The following resources are available in the current version of the API. All are HTTP GETs.

/spaces

Returns all available spaces for the organization associated with the provided key.

Examples:
» https://api.ca.pulseenergy.com/pulse/1/spaces.json
[
    {
        "id":388,
        "label":"Frungy Centre",
        "name":"Frungy Centre",
        "parentId":null,
        "address":"8765 Central Blvd",
        "description":null,
        "spaceType":"Building",
        "spaceUse":"Other",
        "area":{"number":24765.0,"unit":"SquareFeet"},
        "latitude":26.9332845,
        "longitude":-80.134134,
        "occupantCount":100,
        "yearConstructed":null,
        "weeklyOperatingHours":null
    },{
        "id":387,
        "label":"Pik Tower",
        "name":"Pik Tower",
        "parentId":null,
        "address":"456 Broadway Street",
        "description":null,
        "spaceType":"Building",
        "spaceUse":"Other",
        "area":{"number":39654.0,"unit":"SquareFeet"},
        "latitude":42.8891201,
        "longitude":-78.8569344,
        "occupantCount":100,
        "yearConstructed":null,
        "weeklyOperatingHours":null
    }
]
» https://api.ca.pulseenergy.com/pulse/1/spaces.xml
<spaces>
  <space>
    <id>388</id>
    <label>Frungy Centre</label>
    <name>Frungy Centre</name>
    <parentId></parentId>
    <address>8765 Central Blvd</address>
    <description></description>
    <spaceType>Building</spaceType>
    <spaceUse>Other</spaceUse>
    <area>24,765 ft²</area>
    <latitude>26.9332845</latitude>
    <longitude>-80.134134</longitude>
    <occupantCount>100</occupantCount>
    <yearConstructed></yearConstructed>
    <weeklyOperatingHours></weeklyOperatingHours>
  </space>
  <space>
    <id>387</id>
    <label>Pik Tower</label>
    <name>Pik Tower</name>
    <parentId></parentId>
    <address>456 Broadway Street</address>
    <description></description>
    <spaceType>Building</spaceType>
    <spaceUse>Other</spaceUse>
    <area>39,654 ft²</area>
    <latitude>42.8891201</latitude>
    <longitude>-78.8569344</longitude>
    <occupantCount>100</occupantCount>
    <weatherStation></weatherStation>
    <yearConstructed></yearConstructed>
    <weeklyOperatingHours></weeklyOperatingHours>
  </space>
» https://api.ca.pulseenergy.com/pulse/1/spaces.csv
"Name","Address","Notes","Type","Use","Area","Area unit (m2/ft2)","Occupants","Year Constructed","Latitude","Longitude","Time Zone","Parent",
"Frungy Centre", "8765 Central Blvd","Building","Other","24765.0","ft²","100", "26.9332845","-80.134134","America/New_York",
"Pik Tower","456 Broadway Street",,"Building","Other","39654.0", "ft²", "100","42.8891201","-78.8569344","America/New_York",

/spaces/<id>

Returns the space with the specified id for the organization associated with the provided key.

Examples:
» https://api.ca.pulseenergy.com/pulse/1/spaces/388.json
{
	"id":388,
	"label":"Frungy Centre",
	"name":"Frungy Centre",
	"parentId":null,
	"address":"8765 Central Blvd",
	"description":null,
	"spaceType":"Building",
	"spaceUse":"Other",
	"area":{"number":24765.0,"unit":"SquareFeet"},
	"latitude":26.9332845,
	"longitude":-80.134134,
	"occupantCount":100,
	"yearConstructed":null,
	"weeklyOperatingHours":null
}
» https://api.ca.pulseenergy.com/pulse/1/spaces/388.csv
"Name","Address","Notes","Type","Use","Area","Area unit (m2/ft2)","Occupants","Year Constructed","Latitude","Longitude","Time Zone","Parent",
"Frungy Centre","8765 Central Blvd",,"Building","Other","24765.0","ft²","100", "26.9332845","-80.134134","America/New_York",

/spaces/<id>/data

Returns the data associated with the specified space.

Parameters:

Examples:
» https://api.ca.pulseenergy.com/pulse/1/spaces/388/data.json?key=9C3B13239D75E73FDE883C934FF647A1&resource=Electricity&start=2011-01-01&interval=month&quantity=Energy
{
    "id":388,
    "label":"Frungy Centre",
    "unit":"kWh",
    "quantity":"energy",
    "resource":"electricity",
    "start":"2010-12-31T00:00:00-08:00",
    "end":"2011-02-01T00:00:00-08:00",
    "sum":11756.848541666663,
    "data": [
        ["2010-12-31T00:00:00-08:00",359.757625],
        ["2011-01-01T00:00:00-08:00",331.078125],
        ["2011-01-02T00:00:00-08:00",326.5153333333],
        ["2011-01-03T00:00:00-08:00",340.041125],
        ["2011-01-04T00:00:00-08:00",392.0099583333],
        ...
        ["2011-01-31T00:00:00-08:00",390.562125]
    ]
}

/points

Returns all available points for the organization associated with the provided key.

Examples:
» https://api.ca.pulseenergy.com/pulse/1/points.json
[
    {
        "id": 25393,
        "label": "Arilou Energy",
        "unit": "kWh",
        "type": "energy",
        "measurement": "electricity",
        "timezone": "America/Vancouver"
    },
    {
        "id": 456,
        "label": "Arilou Power",
        "unit": "kW",
        "type": "power",
        "measurement": "electricity",
        "timezone": "America/Vancouver"
    }
]
» https://api.ca.pulseenergy.com/pulse/1/points.xml
<points>
    <point>
        <id>25393</id>
        <label>Arilou Energy</label>
        <unit>kWh</unit>
        <type>energy</type>
        <measurement>electricity</measurement>
        <timezone>America/Vancouver</timezone>
    </point>
    <point>
        <id>456</id>
        <label>Arilou Power</label>
        <unit>kW</unit>
        <type>power</type>
        <measurement>electricity</measurement>
        <timezone>America/Vancouver</timezone>
    </point>
</points>

/points/<id>

Returns the point specified by the id.

Examples:
» https://api.ca.pulseenergy.com/pulse/1/points/25393.json
{
    "id": 25393,
    "label": "Arilou Energy",
    "unit": "kWh",
    "type": "energy",
    "measurement": "electricity",
    "timezone": "America/Vancouver"
}
» https://api.ca.pulseenergy.com/pulse/1/points/25393.xml
<point>
    <id>25393</id>
    <label>Arilou Energy</label>
    <unit>kWh</unit>
    <type>energy</type>
    <measurement>electricity</measurement>
    <timezone>America/Vancouver</timezone>
</point>

/points/<id>/data

Returns data for the point specified by the id.

Parameters:

Examples:
» https://api.ca.pulseenergy.com/pulse/1/points/25393/data.xml?interval=week&start=1280919600
<point>
    <id>25393</id>
    <label>Arilou Energy</label>
    <unit>kWh</unit>
    <records start="1280919600" end="1281524400" sum="11361.375">
        <record date="1280919600" value="80.0">
        <record date="1280923200" value="80.75"">
        ...
        <record date="1281517200" value="79.375">
        <record date="1281524400" value="83.75">
    </records>
</point>
» https://api.ca.pulseenergy.com/pulse/1/points/25393/data.json?interval=week&start=2010-08-04T11:00:00.000Z
{
    "id":25393,
    "label":"Arilou Energy",
    "unit":"kWh",
    "start":"2010-08-04T11:00:00.000Z",
    "end":"2010-08-11T11:00:00.000Z",
    "sum":11361.375,
    "data":[
        ["2010-08-04T11:00:00.000Z",80.0],
        ["2010-08-04T12:00:00.000Z",80.75],
        ...
        ["2010-08-11T09:00:00.000Z",79.35],
        ["2010-08-11T03:00:00.000Z",83.75]
    ]
}
» https://api.ca.pulseenergy.com/pulse/1/points/25393/data.json?interval=day

(Assuming today's date is August 13, 2010.)

{
    "id":25393,
    "label":"Arilou Energy",
    "unit":"kWh",
    "start":1281608100,
    "end":1281694500,
    "sum":1674.53,
    "data":[
        [1281608100,76.2],
        [1281609000,87.3],
        ...
        [1281693600,77.5],
        [1281694500,81.1]
    ]
}