Add a Usage Profile
Usage profiles are tied to an account, so when adding a profile you need an accountId or providerAccountId to add it to. Other than that, pretty much all other fields are optional. You just make a POST request with any additional data you want to save. You can add a shell and then later add or update readings and other information, or you can add it all at once.
TIP - The Update Usage Profile endpoint can perform "upserts". If you use your own unique providerProfileId, you can skip calling the Add Usage Profile endpoint (a POST) and go straight to the Update Usage Profile endpoint (PUT) and your profile will be added or updated depending on if it exists or not.
Resource URI
POST /rest/v1/profiles
Examples
Below is a simple example that just adds a profile without any readings. The profileName and description are both optional but are shown here for illustration purposes. The providerProfileId is also optional but has to be unique if supplied. The profile's serviceType will default to "ELECTRICITY" if not passed in (your other option is "SOLAR_PV"), and if this is the account's first profile with the "ELECTRICITY" service type, it will also have its isDefault set to true. You do not need to pass in any bills or reading data but you can if you have them.
{
"providerProfileId": "ELECTRICITY_RESIDENTIAL_CA_2012",
"profileName": "2012 CA Electricity Residential Profile",
"accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa"
}
The response will contain the newly created profile's ID, which you can then use to retrieve or update the profile later.
{
"status": "success",
"count": 1,
"type": "UsageProfile",
"results": [
{
"profileId": "b7559f37-8020-4969-8bd1-48d8c3d58976",
"providerProfileId": "ELECTRICITY_RESIDENTIAL_CA_2012",
"profileName": "2012 CA Electricity Residential Profile",
"accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa",
"serviceTypes": "ELECTRICITY",
"properties": null
}
]
}
Example 1 - Update a Usage Profile
You can update most of the fields on an existing profile using this method. It will only update the fields you have passed in. For instance, if the profile already has a description saved in the database and you do not pass it in, it will not be touched.
If you use your own unique providerProfileId, you can also use this method to create a new profile with that ID. This will let you avoid having to track the Genability-created profileId for your profile.
Resource URI
PUT /rest/v1/profiles
Example 2 - Upsert of monthly Electricity Readings profile
This example will add a new profile (if one with this providerProfileId doesn't exist) and at the same time also add the readings included in the request.
{
"providerAccountId" : "api-eg-008",
"providerProfileId" : "RESIDENTIAL_CA_ELECTRICITY_2012",
"profileName" : "2012 CA Electricity Residential Profile",
"description" : "Residential Electricity Profile",
"isDefault" : true,
"serviceTypes" : "ELECTRICITY",
"sourceId" : "ReadingEntry",
"readingData" : \[
{ "fromDateTime" : "2012-01-01",
"quantityUnit" : "kWh",
"quantityValue" : "700",
"toDateTime" : "2012-02-01"
},
/* edited for length */
{ "fromDateTime" : "2012-12-01",
"quantityUnit" : "kWh",
"quantityValue" : "700",
"toDateTime" : "2013-01-01"
}
]
}
The above call returns the following response.
{
"status": "success",
"count": 1,
"type": "UsageProfile",
"results": [
{
"profileId": "a860df08-31cb-4dd8-961d-523429bf5420",
"providerProfileId": "RESIDENTIAL_CA_ELECTRICITY_2012",
"profileName": "2012 CA Electricity Residential Profile",
"accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa",
"description": "Residential Electricity Profile",
"serviceTypes": "ELECTRICITY",
"source": {
"sourceId": "ReadingEntry",
"name": "Readings"
},
"isDefault": true,
"properties": null
}
]
}
Example 3 - "Upsert" Solar Production Profile with Readings
TIP - This methodology is recommended for actual solar production only. If you're uploading data estimated with PVSyst, Helioscope, or any other tool, we recommend that you use BaselineMeasures instead.
This example will add a new profile (if one with this providerProfileId doesn't exist) that is for a service type of SOLAR_PV rather than ELECTRICITY. It also includes monthly production numbers. If you have hourly, daily, or some other variant, you just change your reading date ranges.
In addition, in this example, we pass the systemSize property (in kW). Including this information on your solar profile allows any charges based on the solar system size to be automatically calculated when the solar profile is referenced in a Savings Analysis.
{
"providerAccountId" : "api-eg-008",
"providerProfileId" : "SOLAR_RESIDENTIAL_CA_2012",
"profileName" : "2012 CA Solar Residential Profile",
"description" : "Residential Solar Profile",
"serviceTypes" : "SOLAR_PV",
"sourceId" : "ReadingEntry",
"properties" : {
"systemSize" : {
"keyName" : "systemSize",
"dataValue" : "5"
}},
"readingData" : \[
{ "fromDateTime" : "2012-01-01",
"quantityUnit" : "kWh",
"quantityValue" : "225",
"toDateTime" : "2012-02-01"
},
/* edited for length */
{ "fromDateTime" : "2012-12-01",
"quantityUnit" : "kWh",
"quantityValue" : "236",
"toDateTime" : "2013-01-01"
}
]
}
The above call returns the following response.
{
"status": "success",
"count": 1,
"type": "UsageProfile",
"results": [
{
"profileId": "3f631a21-9fdd-4daf-a130-02dde375d598",
"providerProfileId": "SOLAR_RESIDENTIAL_CA_2012",
"profileName": "2012 CA Solar Residential Profile",
"accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa",
"description": "Residential Solar Profile",
"serviceTypes": "SOLAR_PV",
"source": {
"sourceId": "ReadingEntry",
"name": "Readings"
},
"properties": null
}
]
}
Example 4 - Generate a Solar Production Profile using the integrated PVWatts
You can also use our integrated PVWatts model to upload a solar profile directly. To use it, set your source.sourceId to PVWatts. We support PVWatts versions 5 and 6. To choose between them, set your source.sourceVersion to 5 or 6. Here are the different parameters available for making the PVWatts call:
| Name | Type | Description |
|---|---|---|
| systemSize | Decimal | The desired system size in kW. Must be between 0.05 and 500,000 kW. |
| moduleType | Integer | The type of module to use. 0 = Standard, 1 = Premium, 2 = Thin Film. |
| azimuth | Integer | The azimuth of the array. 0 = Due north, 180 = Due south. Must be between 0 and 359. |
| tilt | Integer | The tilt of the array. 0 = Flat, 90 = Vertical. Must be between 0 and 90. |
| losses | Decimal | Losses in the system other than from the inverter. Must be between -5 and 99. 0 = no power lost, 99 = 1% of power remaining. |
| inverterEfficiency | Decimal | The efficiency of your inverter. Must be between 90 and 99.5. 90 = 10% of power lost, 99.5 = 0.5% of power lost. Default: 96. |
| trackMode | Integer | The array type and tracking mode. 0 = Fixed - Roof Mounted 1 = Single Axis Backtracking 2 = Double Axis 3 = Fixed - Open Rack 4 = Single Axis | |
| DCACRatio | Decimal | The ratio of the array’s DC rated size to the inverter’s AC rated size. Must be positive. PVWatts v6 and v8 default: 1.2. |
| gcr | Decimal | Ground coverage ratio applies only to arrays with single-axis tracking, and is the ratio of module surface area to the ground or roof occupied by the array. Must be between 0 and 3. Default: 0.4. |
| climateDataset | String | The climate data set that you want to use. Valid options are “nsrdb”, “tmy2”, “tmy3”, and “intl”. PVWatts v6 and v8 default: nsrdb |
| climateDataCorrectionZone | String | For Hawaii Sun Zones, the zone applicable to this analysis. Available values are 200-250, 251-300, and so on up to 601-650. Note that the correction factor will only be used if it applies to the location of the account and the climate dataset that you specify. For example, a value of 601-650 would be applicable and used for Honolulu but would not be used for a system in Los Angeles. |
| climateDataFileId | String | Reference to a specific climate data file to use. Must be a valid ID returned by the PVWatts Solar Dataset Query API. |
| climateDataSearchRadius | Integer | The search radius to use when searching for the closest climate data station (miles). Pass in radius = 0 to use the closest station regardless of the distance. Default: 100. |
| bifaciality | Decimal | The ratio of rear-side efficiency to front-side efficiency. Typically a value between 0.65 and 0.9 provided on the bifacial module datasheeet. This is to account for the fact that photovoltaic cells on the rear of the module are usually less efficient than the cells on the front of the module. The bifaciality does not affect the solar irradiance on the rear of the module. Must be between 0 and 1. |
| albedo | Comma-separated String | “Ground reflectance. A value of 0 would mean that the ground is completely non-reflective, and a value of 1 would mean that it is completely reflective.” Specify a comma-separated string (one or twelve values). Must be between >0 and <1. |
| useWeatherFileAlbedo | Integer | “Use hourly or sub-hourly albedo data from the weather file instead of the monthly albedo values, if available. 0 means do not use weather file albedo values, 1 means use weather file albedo values.” |
| soiling | Comma-separated String | “Reduction in incident solar irradiance caused by dust or other seasonal soiling of the module surface that reduces the radiation incident on the subarray. Soiling losses cause a uniform reduction in the total irradiance incident on each subarray.” Specify a comma-separated string of 12 monthly values. Must be between 0 and 100. |
This example will add a new profile (if one with this providerProfileId doesn't exist) and load it with data from running the integrated NREL PVWATTS solar production model. Here we pass in some specific values for model parameters such as azimuth, tilt, losses, and inverter efficiency. Note that you need to have a valid address on the account because we use the latitude and longitude to look up the location's solar irradiance.
{
"providerAccountId" : "api-eg-08",
"providerProfileId" : "PVWATTS_RESIDENTIAL_FL_2018",
"serviceTypes" : "SOLAR_PV",
"sourceId" : "PVWatts",
"properties" : {
"systemSize" : {
"keyName" : "systemSize",
"dataValue" : "8.25"
},
"azimuth" : {
"keyName" : "azimuth",
"dataValue" : "170"
},
"tilt" : {
"keyName" : "tilt",
"dataValue" : "17"
},
"losses" : {
"keyName" : "losses",
"dataValue" : "14"
},
"inverterEfficiency" : {
"keyName" : "inverterEfficiency",
"dataValue" : "96"
}
}
}
and the above runs PVWatts then saves the results in a BaselineProfile.
Example 5 - Upload a Solar Profile with BaselineMeasure Data
TIP - This methodology is recommended for modeled solar production only. If you're uploading actual production data, we recommend that you use Readings instead.
Estimated solar production data does not usually correspond to the days of a particular year. Instead the estimate for "January 1, 2012" actually represents the expected production for the first day of any year. To model this, you can upload a profile with a series of BaselineMeasure objects as its data rather than ReadingData. Each BaselineMeasure object corresponds with an hour of a generic year, so a full year of solar data will have 8,760 data points.
In addition, in this example, we pass the systemSize property (in kW). Including this information on your solar profile allows any charges based on the solar system size to be automatically calculated when the solar profile is referenced in a Savings Analysis.
To upload a solar profile with baseline measures, you can use the same URL that you do when uploading a normal profile:
PUT /rest/v1/profiles
The request body, however, will be a little bit different:
{
"providerAccountId" : "api-eg-01",
"providerProfileId" : "eg-BaselineMeasures",
"serviceTypes" : "SOLAR_PV",
"sourceId": "SolarPvModel",
"properties" : {
"systemSize" : {
"keyName" : "systemSize",
"dataValue" : "5"
}},
"baselineMeasures": \[
{
"i":1,
"v":10
},
{
"i":2,
"v":20
},
/* edited for length */
{
"i":8759,
"v":20
},
{
"i":8760,
"v":10
}]
}
There are two differences between this profile and the profiles that we've uploaded before. First, the sourceId is set to SolarPvModel. This sourceId lets the API know that you are going to be uploading a profile that uses baselineMeasures instead of readingData. Second, we've got a new property called baselineMeasures that contains the actual measurements. Each measure has only two values: i, denoting where that measurement comes in the overall sequence, and v, denoting the value of that measurement.
Once the profile is uploaded, we can use it just like a normal solar profile when calculating customer savings.
In order to get the baseline measurements back out again, just add the populateBaseline parameter to your Get Usage Profile request and set it to true:
GET /rest/v1/profiles/pid/eg-BaselineMeasures/?populateBaseline=true
Example 6 - Add or Update Readings
When adding new set of readings, POST to the following URL. For updates to existing readings, use a PUT. Otherwise, both accept the same request body structure and return the same response body back.
Resource URI
POST /rest/v1/profiles/{profileId}/readings
PUT /rest/v1/profiles/{profileId}/readings
POST /rest/v1/profiles/pid/{providerProfileId}/readings
PUT /rest/v1/profiles/pid/{providerProfileId}/readings
Request Payload
The request needs the required security parameters. The body of the request contains the usageProfileId to add the readings to and an array of one or more readings to add. More specifically, the readings are in the ReadingData object and the following fields are required (or common) for each reading:
| Name | Type | Description |
|---|---|---|
| fromDateTime | DateTime | Start date and time of this reading. (Optional but typical) |
| toDateTime | DateTime | End date and time of this reading. (Required) |
| quantityUnit | String | The unit of the reading, e.g. kwh. (Required) |
| quantityValue | Decimal | The actual quantity of the reading. (Required) |
Make sure the Content-Type of the body is application/json.
Example POST Request
POST /rest/v1/profiles/e494b54e-430e-4b1b-833b-8783e21eae56/readings
Below is a sample POST body that adds individual reading data items to a usage profile with ID 'e494b54e-430e-4b1b-833b-8783e21eae56'.
{
"usageProfileId": 'e494b54e-430e-4b1b-833b-8783e21eae56',
"readings" : [ {
"fromDateTime" : "2011-08-01T22:30:00.000-0700",
"toDateTime" : "2011-08-01T22:45:00.000-0700",
"quantityUnit" : "kWh",
"quantityValue" : 220
} ]
}