Bulk uploading is an easy way to upload files and large sets of account, profile, and reading data. This is not a REST API. Instead, it’s a standard file upload that you can do from an HTML form (in other words, it’s a multi-file form POST). You can upload either CSV files, or XML files in the Green Button (ESPI) file format. These can be ZIPed up or not. There is a 10 MB limit on the size of the file.

The reading data always belongs to a profile, which in turn belongs to an account. The data can be placed in an existing Profile object, or the act of loading can create a new one.

File Formats

We currently support a number different file formats. These are i) several Comma-separated values (CSV) based formats and ii) and the Green Button (ESPI XML) standard. CSV is common for sharing data and can be exported from MS Excel and other spreadsheet programs. Green Button is a new industry standard that a number of utilities are starting to support (primarily for residential data).

fileFormat Parameter Options

The details of the various options for the fileFormat parameter are described below. Listed here are all of the available options. Make sure to specify the correct format when uploading your data.

Value Description
csv Covers the Powermeter format and the Genability Flexible Column format.
espi Use this for GreenButton data.
pvsyst This is for data exported from PVSyst.
pvsim This is for data exported from PVSim.
helioscope This is for data exported from Helioscope.

Google Powermeter (CSV) Format

This is the “raw” format provided by Google’s now defunct Powermeter app. It’s essentially a CSV, with a header row and 3 columns.

Column Data Type Description
Time ISO DateTime The end date and time of this reading in ISO 8601 format, e.g. January 3, 2010 at 08:00 a.m. would be 20100103T080000.000Z. Midnight is represented as 00 (not 24).
Usage (kWh) Decimal The amount of kWh consumed during the time of the reading, e.g. 33.24531434
IsInitial Integer 1 if the reading is the very first one, 0 otherwise

Example of Powermeter CSV File

Time, Usage (kW h), IsInitial
20100910T182601.000Z,0.003,1
20100910T183602.000Z,0.104,0
20100910T184603.000Z,0.267,0

Genability Flexible Column (CSV) Format

This is our own format for adding and updating reading (and interval) data. To use it, specify a fileFormat of csv. Each row represents one reading for a given account and profile. It is flexible in that the first row (heading row) can be used to define what each column contains. The server is smart enough to read the header row, see what each column contains, and use this information to validate and map each column’s contents to the correct field. The first column has to be the end date and time (toDateTime), the second column has to be the quantity of the reading (quantityValue), but all subsequent columns are optional and can be specified by what is in the header row. If you don’t provide a header row, we only look at the first two columns.

Column Data Type Description
toDateTime ISO DateTime The end date (and optionally time) of this reading in ISO 8601 format, e.g. January 3, 2010 at 08:00 a.m. would be 20100103T080000.000Z. Midnight is represented as 00 (not 24). When no time is supplied, we assume midnight.
quantityValue Decimal The quantity of the reading, e.g. 33.24531434. When no quantityUnit column is supplied, we assume kWh

Optional Additional Columns

There are also a number of optional metadata columns that can be supplied (or not) in any order, if desired.

Column Data Type Description
quantityUnit String “kWh” for consumption, “kW” for billing demand. See Properties for other values.
fromDateTime ISO DateTime When the reading starts.
toDateTime ISO DateTime When the reading ends.
timeOfUseId Integer The unique ID of a specific TOU period that this reading applies to.

Example of a Flexible Column (CSV) Format with a heading row

fromDateTime,quantityValue,quantityUnit,toDateTime,timeOfUseId
2011-01-01,66537,kWh,2011-02-01,1717
2011-02-01,64077,kWh,2011-03-01,1717
2011-03-01,70394,kWh,2011-04-01,1717
2011-04-01,70837,kWh,2011-05-01,1717
2011-05-01,76540,kWh,2011-06-01,1519
2011-06-01,78965,kWh,2011-07-01,1519
2011-07-01,77354,kWh,2011-08-01,1519
2011-08-01,78283,kWh,2011-09-01,1519
2011-09-01,78451,kWh,2011-10-01,1519
2011-10-01,73647,kWh,2011-11-01,1519
2011-11-01,71175,kWh,2011-12-01,1717
2011-12-01,68929,kWh,2012-01-01,1717

Example of a Flexible Column (CSV) Format without a heading row. Only toDateTime and quantityValue are specified

20100101T000000.000Z,33.24531434
20100101T010000.000Z,33.63953172
20100101T020000.000Z,29.69534128

Green Button (ESPI XML) Format

Green Button is an effort heavily promoted by by the White House to empower users with access to data about their energy consumption. Many utilities are making this data available for their residential customers (list here). This XML can be uploaded as-is into a Genability account.

A description of the format and samples of Green Button XML file can be found on greenbuttondata.org. We also have some additional samples for download here.

POSTing the File

To upload any of the above file formats requires a HTML form POST. Along with the actual files contents, the form will contain a number of other name-value pairs that define information about the account and/or profile this data is being loaded into, and what should happen after the file is successfully loaded.

Here’s an example of a HTML Form that would post a Green Button (ESPI XML) file:

1
2
3
4
5
6
7
8
<form action="https://api.genability.com/rest/v1/loader/account/up.html"
		method="post" enctype="multipart/form-data">
    <input type="file" name="fileData" />
    <input type="hidden" name="fileFormat" value="espi" />
    <input type="hidden" name="redirectPath" value="http://www.costbutton.com/" />
    <input type="hidden" name="customerClass" value="RESIDENTIAL" />
    <input type="hidden" name="providerAccountId" value="{providerAccountId}" />
</form>

Constructing the Form

Form Tag

Your form tag needs the action URL, which will end with either "html" or "json" depending on what type of response you want. If you set it to "html" you will also need to set the redirectPath property. This will be the path that your user will be returned to once the upload is completed successfully. By using "json", you have a little more programmatic control and will get back a JSON response payload with information about the uploads results. Both of these options are described more below. Note that you also need a method of "post" and an enctype of "multipart/form-data".

1
2
<form action="https://api.genability.com/rest/v1/loader/account/up.html"
		method="post" enctype="multipart/form-data">

Request Parameters

Along with the file itself (in the fileData field) there are a number of additional required and optional properties that you need to pass in with the form post:

Name Type Description
fileData File Required. Actual Files data. Can be zipped or unzipped.
fileFormat String Optional ("csv" assumed when missing).
redirectPath URL or Path Required when "html" response, but ignored for "json" response.
accountId String Optional. UUID of an existing account. Don’t set if adding a new account. Note also you can use providerAccountId to find your existing account if you know that but not this (i.e. use your ID not ours).
providerAccountId String Optional. Your unique account ID. Set this or accountId if updating an existing account. You can also set this if you want to add a new account.
customerClass String Optional. Only used when adding a new account. Set to "RESIDENTIAL" or "GENERAL".
profileId String Optional. Use this to save data to a specific existing account. Don’t set otherwise.
useDefaultBillingProfile Boolean Optional. Use this to save to the profile that is the default one. This is useful for updating an existing profile without having to know the profile’s ID
profileName String Optional. Only needed when adding a new profile. Ignored otherwise.
profileDescription String Optional. Only needed when adding a new profile. Ignored otherwise.

Response (HTML Success Case)

When you set the extension of your POST action URL to "html" (and don’t forget to set the redirectPath, too!), if the file is successfully uploaded, we will return an HTTP Redirect to the redirectPath you sent us. Appended to the query string of this redirect are the following name/value pairs so that you know what happened:

Name Type Description
status String Our standard response status values
accountId String UUID of the Account added or updated (our unique ID)

Response (JSON Success Case)

When you set the extension of your POST action URL to “json”, if the file is successfully uploaded, will will return a payload in our standard JSON Restful response format containing the usage profile where the readings were saved.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "status":"success",
   "count":1,
   "type":"UsageProfile",
   "results":[
      {
         "profileId":"af3a2d0e-22e1-48c0-9633-110173b2da8a",
         "profileName":"Joes Surf Shack",
         "accountId":"6358a60b-abc2-4e32-9e0e-8e4662267826",
         "dataStatus":null
      }
   ]
}

History

  • 3/5/2015 - Formatting update
  • Large upgrade with flexible format, more optional, and new endpoints - 5/25/2012
  • Added info on Green Button support - 1/19/2012
  • Moved to Beta - 1/10/2012
  • Update - 10/26/2011 - initial Alpha Version Released