Usage Profile

Overview

A usage profile organizes together one or more series' of usage data. This data can include electricity consumption (kWh) or demand (kW). It can take the form of bills or meter readings, and can be for electricity purchased from the utility or on-site solar energy. They can also take into account usage reduction through energy efficiency. Profiles belong to an Account object, and it is typical, although not required, to have at least one profile per account.

The data structure of a Profile object consists of a "header" that denotes key information about it such as its unique profileId (that Genability generates) or your unique providerProfileId, its name, serviceType and other properties. It also has a summary of its usage info, as well the inputted data points themselves. The data inputs can come in two flavors: bills and readings. Readings are most commonly from electricity metering and likely will be in uniform durations. They can however record values at irregular intervals, such as billing cycles or when measurements don't occur at regular times. A reading can be for a given interval or as of a particular point in time.

Profiles also have a ReadingSummary object for each series that denotes the number of readings for that series. The summary also contains the date and time range for the series and other useful data points.

There are a number of different ways you can add (or edit) reading data to a profile. The different methods available are intended for use in different scenarios:

  • Real Time Interval API - use this approach when adding one or a small number of intervals. This is optimized for real time feeds such as sending us updates every 15 minutes or hour.
  • Reading API - use this approach when programmatically sending number of irregular readings. This is designed for data that does not fit into intervals.
  • Bulk Loading via File Upload- ideal for batch uploading of several (hundreds or thousands) of intervals or readings. This approach is essentially a CSV file upload.

Data Definitions

Usage Profile

Each profile has a unique profileId (a UUID) that Genability generates when the profile is created, but you can also use your own providerProfileId as an alternate key. Each profile also has an optional name and an optional description that can be used for identifying and organizing your profiles. These are optional because you might not always have a logical profile name when you create the profile. You can always come back later and update it. Note that we do not enforce unique profile names. Every profile needs to belong to an account, so accountId or providerAccountId is required when adding a profile.

Name Type Fields Description
profileId String M Unique Genability ID (UUID) for this usage profile.
profileName String M (Optional) Your specified name for this usage profile.
accountId String M Required accountId for this usage profile. This is useful for linking usage profiles to your own customer Ids.
description String Optional description for this Usage Profile.
serviceTypes String Comma separated strings of the types of service this profile denotes. Current types include "ELECTRICITY" and "SOLAR_PV".
source Source Optional. Source contains a sourceId and name (both strings). Uniquely identify the source of this profile. e.g. "PVWatts"
isDefault Boolean Denotes whether this is the default profile for the service type. Default profiles are used for calcs when no profile is specified.
properties Array of PropertyData Our standard collection of PropertyData denoting properties specific to this Profile.
dataStatus Integer Read-only value that Genability maintains to show how up-to-date the profile number crunching is. 1=processing, 2= done, 3=error (we auto-fix 3)
readingDataSummaries Array of ReadingDataSummary See below for details of ReadingDataSummary.
intervals Array of IntervalInfo Data See below for details of IntervalInfo.
readingData Array of ReadingData See below for details of ReadingData.
baselineMeasures Array of BaselineMeasure (Optional) For estimated solar production, your profile doesn't necessarily have to correspond to a particular year. You can use this field to input an array of generic datapoints corresponding to the hours of a year rather than specific dates.

SourceId Options

As you'll see in the examples, you won't usually construct a full Source object when uploading a usage profile. Instead, you can just set the sourceId property. What sourceId should you use and when should you use it? There are three options that you should choose from:

Name Description
ReadingEntry When uploading any kind of usage data through the profile endpoint, you should use ReadingEntry.
PVWatts If you want to have the integrated PVWatts engine create a solar profile for you, use a sourceId of PVWatts. This will default to PVWatts v4. If you want to use v5, you'll need to create a full Source object. See below for an example.
SolarPvModel If you have any any other kind of solar simulation data that you want to upload through the profile endpoint, use SolarPvModel. If you have PVSyst or Helioscope CSVs, you can also use the File Uploader.

Reading Data Summary

The profile has one ReadingDataSummary object for each series of data (a series is a unique quantityUnit). These are read-only. The system creates and updates them as you add and update reading data to your profile. They provide a high level summary of the readings contained in each data series in this Profile, including the number of readings and the start and end dates of the reading range.

Name Type Fields Description
quantityUnit String Denotes the series for which this summary applies.
numberOfReadings Long The number of Reading Data elements within this series.
firstStartTime DateTime Date and time of the earliest reading in the series.
lastEndTime DateTime Date and time of the last reading in the series.

Reading Data

ReadingData objects contain the point in time readings of a usage profile. There are typically hundreds or thousands of reading data elements per usage profile.

TIP: for the best accuracy, use 15-minute reading data, especially for Commercial & Industrial accounts. For Residential, you can use hourly (8760) readings without loss of accuracy for the vast majority of tariffs. Each reading has a field called quantityUnit that denotes what the reading is measuring, and thus which data series it belongs to. The most typical 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.

Name Type Fields Description
keyName String The type of data this reading represents. Typically will be 'consumption'.
fromDateTime DateTime Date and time this reading starts.
toDateTime DateTime Date and time this reading ends.
duration Decimal Length of this interval.
timeAccuracy Integer Value representing the accuracy, in ms, of the time reading.
quantityUnit String Unit of this reading. Typically will be 'kWh'.
quantityValue Decimal Value of this reading. e.g. the number of kWh.
quantityAccuracy Decimal Indicator of the accuracy of the reading, in the same units as the quantityValue.
touType String One of OFF_PEAK, PARTIAL_PEAK, ON_PEAK, or CRITICAL_PEAK. Used for uploading TOU-based energy consumption data. Make sure to read the how-to for more details on uploading TOU usage data.

Interval Info

The intervals property holds an array of IntervalInfo objects, each of which denotes the costs, rates and quantities for an fixed period of time, or interval. These are generated by Genability and are the normalized cost and usage data for a uniform time span, such as every hour, day, month or year. You should not pass in interval data. Here's an example of what you'll get back:

{
    "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
    }
}

Operations

Get Usage Profiles

Query all your usage profiles or ones that match a given criteria. Typical searches involve an accountId (i.e. get me all the profiles for this account), and/or a serviceType. Full request parameters are listed below.

Resource URI

GET /rest/v1/profiles

Request Parameters

The required security parameters should be included. You can also use the standard pagination or search and sort options. The following additional parameters are supported, too:

Name Type Description
accountId String Filter all the Profiles for a specific account. (Optional)
profileName String Filter all the Profiles that match a given name. (Optional)
serviceTypes String Comma separated string of service types to filter by. Possible values include: ELECTRICITY, SOLAR_PV (or solarPv). This is case insensitive. (Optional)
isDefault Boolean Only return the profiles that are defaults (true) or not defaults (false). (Optional)

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 a Usage Profile with(out) Intervals or Readings

You can retrieve a specific usage profile, with or without its interval or data, using this method.

Resource URI

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

Request Parameters

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

Name Type Description
groupBy String The groupBy value denotes what duration of interval data to return (or group by). When this field is not set, the intervals are not returned. When set, the possible values are: "YEAR", "MONTH", "DAY", "HOUR", "QTRHOUR". (Optional)
clipBy String clipBy is optional and should only be set when groupBy (above) is set. clipBy allows you to control the behavior in the case where groupBy and the requested date range do not line up exactly. Possible values are: "OUTER", "INNER". For example, you request interval data and specify groupBy=MONTH with a date range of April 15, 2012 through June 15, 2012, OUTER will include all months that overlap at least part of the requested range, and the response will include the months of April, May and June. INNER will only include the full months within the requested range, so only May is returned. When you pass in a groupBy but do not specific clipBy, INNER is used. (Optional)
populateReadings Boolean When true the results will contain Reading Data. The default is false. Note, Reading Data Summaries are always returned when getting a Usage Profile independent of the value of this flag. (Optional). NOTE: this used to be called populateReadingData, which has been deprecated but still works (for now).
populateBaseline Boolean When true, the results will contain an array of Baseline Measures. Only applies for profiles that were uploaded with them. See below for when and how to do this.
fromDateTime DateTime Start date (with or without a time) of the date range to return intervals and/or readings for. (Optional)
toDateTime DateTime End date (with or without a time) of the date range to return intervals and/or readings for. (Optional)
autoBaseline Boolean This field enables intelligent baselining feature, which allow you to move usage data to a different time period. (Optional, Default=false). When you set this field to true, also set the fromDateTime and toDateTime to the range you want to move usage data to.
useIntelligentBaselining Boolean This field works in conjunction with autoBaseline (above) and determines how to interpolate and extrapolate usage data when that is set to true. Read intelligent baselining for details.
fields String To just get the dataStatus field, pass in "dataStatus" (good for polling whether the number crunching is complete). Otherwise ignore this field (Optional)

Example 1 - no intervals

To just get the profile without any intervals or readings you don't need any 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 - data status

To check on a profile's data status, add the fields parameter with a value of dataStatus. Great for polling to see if any asynchronous processing is done.

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 - get interval data

To get a profile with its interval data you use the groupBy argument. It's good practice to also set the populateIntervals to true. You can specify a date range, pagination and more. Here we are returning 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 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 saving. You can add a shell and then later add or update readings and other information, or you can add it all at once.

PRO 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 if supplied has to be unique. 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 it 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 updates 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

NOTE: 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 an 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 4 and 5. To choose between them, set your source.sourceVersion to 4 or 5. 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 (PVWatts v5 only) 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.
derate Decimal (PVWatts v4 only) The total derate for your system. 1 = no derate, 0 = 100% derate (no production remaining)
losses Decimal (PVWatts v5 only) Losses in the system other than the inverter. Must be between -5 and 99. 0 = no energy lost, 99 = 1% of energy remaining.
inverterEfficiency Decimal (PVWatts v5 only) The efficiency of your inverter. Must be between 90 and 99.5. 90 = 10% of energy lost, 99.5 = 0.5% of energy lost.
trackMode Integer Set the racking type of the array.
0 = Fixed - Roof Mounted (Fixed -- PVWatts v4)
1 = Single Axis Backtracking (Single Axis -- PVWatts v4)
2 = Double Axis
3 = Fixed - Open Rack (Fixed -- PVWatts v4)
4 = Single Axis
climateDataset String The climate data set that you want to use. Valid options are "tmy2", "tmy3", and "intl".
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 is applicable to the location of the account and the weather 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.

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. More details of our PVWATTS integration can be found on our user help center documentation. Here we pass in some specific values for model parameters such as azimuth. 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-008",
  "providerProfileId" : "PVWATTS_RESIDENTIAL_CA_2012",
  "serviceTypes" : "SOLAR_PV",
  "sourceId" : "PVWatts",
  "properties" : {
    "systemSize" : {
      "keyName" : "systemSize",
      "dataValue" : "8.25"
    },
    "azimuth" : {
      "keyName" : "azimuth",
      "dataValue" : "170"
    },
    "derate" : {
      "keyName" : "derate",
      "dataValue" : "0.816"
    },
    "tilt" : {
      "keyName" : "tilt",
      "dataValue" : "17"
    }
  }
}

The above runs PVWatts then saves the results in a BaselineProfile.

Example 5 - Upload a Solar Profile with BaselineMeasure Data

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 an 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 request and set it to true:

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

Example 6 - Delete a Usage Profile

You can delete a usage profile at any time. Use use a HTTP DELETE with the profile's ID in the URL. You will get the standard success or error response back. Be careful. This is a "hard" delete and your data is really purged. No going back!

Resource URI

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

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