Upload Common File Formats

Upload CSV, Green Button ESPI XML, PVSyst, or Helioscope files into account profiles using the file loader form POST.

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 upload can create a new one.

Prerequisites

1. Create or identify the customer account.
2. Decide whether the upload should use an existing profile or create a new profile.
3. Prepare the file in one of the supported formats.

File upload workflow

1. Choose the correct fileFormat.
2. Prepare the file using the expected format.
3. Decide whether to load data into an existing profile or create a new profile.
4. Build a multipart/form-data POST request.
5. Choose an HTML redirect response or a JSON response.
6. Read the returned account or profile IDs.

Supported file formats

We currently support several file formats, including comma-separated values (CSV) based formats 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 an industry standard that a number of utilities support, primarily for residential data.

fileFormat parameter options

The table below lists the available fileFormat values. 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 (kWh), IsInitial
20100910T182601.000Z,0.003,1
20100910T183602.000Z,0.104,0
20100910T184603.000Z,0.267,0

Arcadia Flexible Column (CSV) format

This is our 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 because the first row, the heading row, can define what each column contains. The server reads the header row, identifies each column, and uses this information to validate and map each column's contents to the correct field. The first column must be the end date and time (toDateTime), and the second column must be the quantity of the reading (quantityValue). All subsequent columns are optional and can be specified by the header row. If you don't provide a header row, we only look at the first two columns.

Use the Arcadia Flexible Column CSV format for new CSV uploads unless you need compatibility with an existing Powermeter export.

If your data has gaps, include fromDateTime so each row has an explicit start and end time. Without fromDateTime, the loader infers each reading starts when the previous row ends, which can turn a gap into one large continuous reading period.

Optional additional columns

You can also supply optional metadata columns in any order.

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 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 an Arcadia account.

A description of the format and samples of Green Button XML files can be found on greenbuttondata.org.

Post the file

Uploading any of the above file formats requires an HTML form POST. Along with the actual file contents, the form contains name-value pairs that define information about the account or profile where the data is being loaded, and what should happen after the file is successfully loaded.

The following example shows an HTML form that posts a Green Button (ESPI XML) file:

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

Construct 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 also need to set the redirectPath property. This is the path that your user will be returned to once the upload is completed successfully. By using .json, you have more programmatic control and will get back a JSON response payload with information about the upload results. Both options are described below. You also need a method of "post" and an enctype of "multipart/form-data".

Use the .json suffix for programmatic uploads:

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

<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 many 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 set the redirectPath, if the file is successfully uploaded, we 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, we return a payload in our standard JSON RESTful response format containing the usage profile where the readings were saved.

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

Next steps

After uploading file data, you can:

• Retrieve the created profile
• Run an Account Cost Calculation
• Run a Savings Analysis
• Review the Profile API