Profiles API

Use the Profiles API to store usage, demand, solar production, or modeled baseline data for an account.

Profiles belong to an Account. A profile can contain bill data, interval readings, solar production data, or baseline measures used in account calculations and savings analyses. For the full profile workflow, see Profile APIs Overview.

Data definitions

Profile

Each profile has a unique profileId, which is a UUID generated by Arcadia when the profile is created. You can also use your own providerProfileId as an alternate key.

Each profile can include an optional name and description for organizing profiles. Profile names are not required and are not enforced as unique. Every profile must belong to an account, so accountId or providerAccountId is required when adding a profile.

Source ID options

When uploading a usage profile, you usually do not need to construct a full Source object. Set the sourceId property instead. Choose one of these sourceId values based on the profile data source:

Reading data summary

The profile has one ReadingDataSummary object for each data series. A series is identified by a unique quantityUnit. These summaries are read-only. Switch creates and updates them as you add and update profile reading data.

Use reading data summaries to inspect the number of readings and the start and end dates for each data series in a profile.

Reading data

ReadingData objects contain the point-in-time or interval readings for a usage profile. A usage profile can contain hundreds or thousands of reading data elements.

For the best accuracy, use 15-minute reading data, especially for commercial and industrial accounts. For residential accounts, hourly readings (8,760 values for a standard year) are accurate for most tariffs.

Each reading has a quantityUnit field that identifies what the reading measures and which data series it belongs to. The most common quantityUnit values are:

• consumption (kWh) / demand (kW)
• apparent power: kVA and kVAh
• reactive power: kVAR and kVARh

When these quantity units appear in a usage profile, they will be used for calculating electricity cost in a cost calculation or a savings analysis when a tariff has charges denominated in those units. Other quantity units like temperature or occupancy can be used as reading data, but they will not be referenced in calculations.

Interval info

The intervals property holds an array of IntervalInfo objects. Each object represents costs, rates, and quantities for a fixed period of time.

Arcadia generates interval data as normalized cost and usage data for a uniform time span, such as every hour, day, month, or year. Do not pass interval data in profile requests.

This example shows returned interval data:

## Next steps

1. Return to [Profile APIs Overview](/reference/profile-api) to choose another profile workflow.
2. Use [Storage Profiles API](/reference/storage-profile-api) to model battery storage behavior and generate post-storage profiles.
3. Use [Account Cost Calculation](/reference/account-cost-calculation) or [Analysis APIs](/reference/analysis-apis-1) with profile data to calculate costs or savings.json
{
    "fromDateTime": "2012-04-01T00:00:00+00:00",
    "toDateTime": "2012-04-01T01:00:00+00:00",
    "duration": 3600000,
    "kWh": {
        "quantityAmount": 100,
        "rateAmount": 0.14,
        "costAmount": 1.4
    },
    "kW": {
        "quantityAmount": 10,
        "rateAmount": 0.25,
        "costAmount": 2.5
    },
    "total": {
        "quantityAmount": 100,
        "rateAmount": 0.39,
        "costAmount": 3.9
    }
}

Get Profiles

Query all usage profiles or profiles that match specific criteria. Common searches filter by accountId or serviceType.

Resource URI

GET /rest/v1/profiles

Request parameters

Example

GET /rest/v1/profiles?accountId=abc123

Below is a sample response containing the usage profiles for a given account.

{
    "status": "success",
    "count": 2,
    "type": "UsageProfile",
    "results": [
    {
        "profileId": "d89edf61-318c-44a3-b894-b6d1af44fbf9",
        "profileName": "Residential-Columbus Southern ",
        "accountId": "3473559f-4e4d-4e82-be51-e6c1dc6663aa",
        "serviceTypes": "ELECTRICITY",
        "dataStatus": 2,
        "readingDataSummaries": [
        {
            "quantityUnit": "kWh",
            "fromDateTime": "2011-01-01T00:00:00+00:00",
            "toDateTime": "2011-12-31T23:00:00+00:00",
            "numberOfReadings": 8760
        }]
    },
    {
        "profileId": "db34897e-1feb-4249-8512-219842398132",
        "profileName": "Atl SM OF",
        "accountId": "3473559f-4e4d-4e82-be51-e6c1dc6663aa",
        "serviceTypes": "ELECTRICITY",
        "dataStatus": 2,
        "readingDataSummaries": [
        {
            "quantityUnit": "kWh",
            "fromDateTime": "2011-01-01T00:00:00+00:00",
            "toDateTime": "2011-12-31T23:00:00+00:00",
            "numberOfReadings": 8760
        }]
    }
  ]
}

Get One Profile With or Without Intervals or Readings

Retrieve a specific usage profile with or without intervals, readings, or baseline measures.

Resource URI

GET /rest/v1/profiles/{profileId}
GET /rest/v1/profiles/pid/{providerProfileId}

Request Parameters

Along with the required authentication parameters and the profileId or providerProfileId, the following parameters are available as part of the request:

Example 1: No intervals or readings

To get the profile without intervals or readings, omit query string arguments:

GET /rest/v1/profiles/b7559f37-8020-4969-8bd1-48d8c3d58976
GET /rest/v1/profiles/pid/ELECTRICITY_RESIDENTIAL_CA_2012

Either one of the above URLs will return the following:

{
  "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",
         "description": "Residential Electricity Profile",
         "serviceTypes": "ELECTRICITY",
         "source": {
            "sourceId": "ReadingEntry",
            "name": "Readings"
         },
         "isDefault": true,
         "dataStatus": 2,
         "properties": null,
         "readingDataSummaries": [
            {
               "quantityUnit": "kWh",
               "fromDateTime": "2012-01-01T00:00:00+00:00",
               "toDateTime": "2013-01-01T00:00:00+00:00",
               "numberOfReadings": 12
            }
         ]
      }
   ]
}

Example 2: Data status

To check a profile's data status, add the fields parameter with a value of dataStatus. Use this field when polling for asynchronous processing completion.

GET /rest/v1/profiles/180a0e07-c5bc-4f7e-8e01-34794f0d99a7?fields=dataStatus

{
  "status": "success",
   "count": 1,
   "type": "UsageProfile",
   "results": [
      {
         "profileId": "b7559f37-8020-4969-8bd1-48d8c3d58976",
         "providerProfileId": "ELECTRICITY_RESIDENTIAL_CA_2012",
         "dataStatus": 2
      }
   ]
}

Example 3: Get interval data

To get a profile with interval data, use the groupBy argument and set populateIntervals=true. You can also specify a date range, pagination, and other supported parameters.

This abbreviated example returns intervals grouped by MONTH:

GET /rest/v1/profiles/b7559f37-8020-4969-8bd1-48d8c3d58976?populateIntervals=true&groupBy=MONTH
GET /rest/v1/profiles/pid/ELECTRICITY_RESIDENTIAL_CA_2012?populateIntervals=true&groupBy=MONTH

{
  "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",
         "description": "Residential Electricity Profile",
         "serviceTypes": "ELECTRICITY",
         "source": {
            "sourceId": "ReadingEntry",
            "name": "Readings"
         },
         "isDefault": true,
         "dataStatus": 2,
         "properties": null,
         "readingDataSummaries": [
            {
               "quantityUnit": "kWh",
               "fromDateTime": "2012-01-01T00:00:00+00:00",
               "toDateTime": "2013-01-01T00:00:00+00:00",
               "numberOfReadings": 12
            }
         ],
         "readings": {
            "totalCount": 12,
            "pageCount": 0,
            "pageStart": 0
         },
         "intervals": {
            "totalCount": 12,
            "pageCount": 25,
            "pageStart": 0,
            "list": [
               {
                  "fromDateTime": "2012-01-01T00:00:00+00:00",
                  "toDateTime": "2012-02-01T00:00:00+00:00",
                  "duration": 2678400000,
                  "kWh": {
                     "quantityAmount": 699.9998,
                     "rateAmount": 0
                  },
                  "kW": {
                     "quantityAmount": 0.94086,
                     "rateAmount": 0
                  }
               },

			   /* edited for length */

               {
                  "fromDateTime": "2012-12-01T00:00:00+00:00",
                  "toDateTime": "2013-01-01T00:00:00+00:00",
                  "duration": 2678400000,
                  "kWh": {
                     "quantityAmount": 699.9998,
                     "rateAmount": 0
                  },
                  "kW": {
                     "quantityAmount": 0.94086,
                     "rateAmount": 0
                  }
               }
            ]
         }
      }
   ]
}

Add a Profile

Usage profiles are tied to an account, so include an accountId or providerAccountId when adding a profile. Most other fields are optional.

You can create a shell profile and add readings later, or create the profile with readings and other profile data in the same request.

Resource URI

POST /rest/v1/profiles

Examples

This example adds a profile without readings. The profileName, description, and providerProfileId fields are optional, but providerProfileId 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. You do not need to pass bills or reading data when creating the profile.

{
     "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 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 remain unchanged.

If you pass in a usage reading for a time frame that already exists on the profile, the usage will be overwritten. Conversely, if you pass in readings for additional time periods, they will be added to the profile along with any existing usage readings. Making a PUT request to the profile with readings for time periods that do not already exist in the profile will not overwrite the existing usage readings on the profile.

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

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

You can 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.

Example 5 - Upload a solar profile with BaselineMeasure data

Use baseline measures for modeled solar production. If you are uploading actual production data, use readings instead.

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.

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

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

Example 6 - Delete a Profile

You can delete a usage profile at any time. Use HTTP DELETE with the profile ID in the URL. Profile deletion is a hard delete, and the profile data is permanently removed.

Resource URI

DELETE /rest/v1/profiles/{profileId}
DELETE /rest/v1/profiles/pid/{providerProfileId}

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

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