Add or Update Profiles

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.

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