Create a usage profile, update an existing profile, or upsert a profile using your providerProfileId.

Usage profiles are tied to an account, so include an accountId or providerAccountId when creating a profile. Most other fields are optional. You can create an empty profile and add readings later, or create the profile with readings and other data in the same request.

For the full profile data model, profile workflow, reading formats, solar profile options, and detailed examples, see Profiles API.

Resource URI

PUT /rest/v1/profiles

Common request body fields

Example

This example upserts a profile without readings. The profileName and description fields are optional but shown for context. The providerProfileId field is optional, but it must be unique if supplied.

The profile's serviceTypes value defaults to ELECTRICITY if not passed. You can also set serviceTypes to SOLAR_PV. If this is the account's first ELECTRICITY profile, isDefault is set to true.

{  
     "providerProfileId": "ELECTRICITY_RESIDENTIAL_CA_2012",  
     "profileName": "2012 CA Electricity Residential Profile",  
     "accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa"  
}

The response contains the new profile's profileId, which you can 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  
      }  
   ]  
}

Optional: Update or upsert a profile

Update most fields on an existing profile with this method. The request only updates fields that you pass in. For example, if the profile already has a description and you omit description, the existing description remains unchanged.

If you use a unique providerProfileId, you can also use this method to create a new profile with that ID. This lets you avoid tracking the Arcadia-generated profileId in your system.

Resource URI

PUT /rest/v1/profiles

Optional: Upsert monthly electricity readings

This example creates a new profile if one with this providerProfileId does not exist. It also adds 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"
    },
    {
      "fromDateTime": "2012-12-01",
      "quantityUnit": "kWh",
      "quantityValue": "700",
      "toDateTime": "2013-01-01"
    }
  ]
}

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

Optional: Generate a solar production profile using integrated PVWatts

Use the integrated PVWatts model to upload a solar profile directly. To use it, set source.sourceId to PVWatts. Switch supports PVWatts versions 5 and 6. To choose between them, set source.sourceVersion to 5 or 6.

The following parameters are available for PVWatts requests:

This example creates a new profile if one with this providerProfileId does not exist and loads it with data from the integrated NREL PVWatts solar production model. The request passes model parameters such as azimuth, tilt, losses, and inverter efficiency.

The account must have a valid address because Switch uses 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"  
    }  
  }  
}

The request runs PVWatts and saves the results in a baseline profile.

Optional: Upload a solar profile with BaselineMeasure data

Estimated solar production data does not usually correspond to the days of a specific year. Instead, the estimate for "January 1, 2012" represents expected production for the first day of any year. To model this, upload a profile with a series of BaselineMeasure objects instead of ReadingData.

Each BaselineMeasure object corresponds to one hour of a generic year, so a full year of solar data has 8,760 data points.

This example also passes the systemSize property in kW. Including this information on the solar profile allows charges based on solar system size to be calculated automatically 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
  }]
}

This profile differs from a readings-based profile in two ways. First, sourceId is set to SolarPvModel, which tells the API that the profile uses baselineMeasures instead of readingData. Second, the baselineMeasures property contains the measurements. Each measure has i, which denotes where the measurement appears in the sequence, and v, which denotes the measurement value.

After the profile is uploaded, you can use it like a normal solar profile when calculating customer savings.

To retrieve baseline measurements, add the populateBaseline parameter to your Get Usage Profile request and set it to true:

GET /rest/v1/profiles/pid/eg-BaselineMeasures?populateBaseline=true

Optional: Add or update readings

When adding a new set of readings, send a POST request. To update existing readings, send a PUT request. Both methods accept the same request body structure and return the same response body.

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 requires authentication. The request body contains the usageProfileId to add readings to and an array of one or more readings. Readings use the ReadingData object. The following fields are required or common for each reading:

Make sure the Content-Type of the body is application/json.

Example POST request

POST /rest/v1/profiles/e494b54e-430e-4b1b-833b-8783e21eae56/readings

This POST body 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  
  } ]  
}