Upload Common File Formats
Upload CSV, Green Button ESPI XML, PVSyst, or Helioscope files into account profiles using the file loader form POST.
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
- Create or identify the customer account.
- Decide whether the upload should use an existing profile or create a new profile.
- Prepare the file in one of the supported formats.
File upload workflow
- Choose the correct
fileFormat. - Prepare the file using the expected format.
- Decide whether to load data into an existing profile or create a new profile.
- Build a
multipart/form-dataPOST request. - Choose an HTML redirect response or a JSON response.
- Read the returned account or profile IDs.
Supported file formats
Choose from the supported formats below, including comma-separated values (CSV) and Green Button (ESPI XML). You can export CSV files from Microsoft Excel and other spreadsheet programs. Green Button is an industry standard supported by a number of utilities, primarily for residential data.
| Use case | Recommended fileFormat |
|---|---|
| Upload readings from a spreadsheet | csv |
| Upload Green Button utility data | espi |
| Upload PVSyst solar production data | pvsyst |
| Upload Helioscope solar production data | helioscope |
fileFormat parameter options
fileFormat parameter optionsThe table below lists the available fileFormat values. Specify the correct format when uploading your data.
| Value | Description |
|---|---|
| csv | Covers the Powermeter format and the Arcadia Flexible Column format. |
| espi | Use this for GreenButton data. |
| pvsyst | This is for data exported from PVSyst. |
| 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 (kWh), IsInitial
20100910T182601.000Z,0.003,1
20100910T183602.000Z,0.104,0
20100910T184603.000Z,0.267,0Arcadia Flexible Column (CSV) format
Use the Arcadia Flexible Column format to add or update reading and interval data. Set fileFormat to csv. Each row represents 1 reading for an account and profile.
Include a header row to identify each column. The server uses the headers to validate and map each column's contents to the correct field. Without a header row, the loader reads only the first 2 columns: toDateTime followed by quantityValue. With a header row, you can include optional columns in any order, as shown in the example below.
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
fromDateTimeso each row has an explicit start and end time. WithoutfromDateTime, the loader infers each reading starts when the previous row ends, which can turn a gap into one large continuous reading period.
| 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
You can also supply optional metadata columns in any order.
| 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,1717Example 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.69534128Green Button (ESPI XML) format
Green Button provides access to energy consumption data. Many utilities make this data available to residential customers. Upload the Green Button XML 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.
| Response mode | Action URL suffix | Use when |
|---|---|---|
| HTML redirect | .html | A browser form should redirect the user after upload. |
| JSON response | .json | Your application needs to inspect upload results programmatically. |
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:
| Name | Type | Description |
|---|---|---|
| fileData | File | Required. Actual file 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 profile. 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)
Set the POST action URL suffix to .html and provide redirectPath to redirect the browser after a successful upload. The response redirects to redirectPath with the following query parameters:
| Name | Type | Description |
|---|---|---|
status | String | Standard API response status. |
accountId | String | Arcadia-generated UUID of the account added or updated. |
Response (JSON success case)
Set the POST action URL suffix to .json to receive a JSON response after a successful upload. The response contains the usage profile where the loader saved the readings.
{
"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:
Updated about 22 hours ago
