Use our File Uploader with Common File Formats

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.

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.

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.

Optional Additional Columns

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

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:

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:

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
      }
   ]
}