Usage Profiles

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.

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:

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.

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.

Interval Info

The intervals property holds an array of IntervalInfo objects, each of which denotes the costs, rates and quantities for a 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "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 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 parameters are supported too:

Example

GET /rest/v1/profiles?accountId=abc123

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "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 intervals or readings, 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:

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
   "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

1
2
3
4
5
6
7
8
9
10
11
12
{
   "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
   "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.

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.

1
2
3
4
5
{
     "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
   "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "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 6 and 8 until version 6 is depreciated in January 2024 after which the version 8 will be the default. To choose between them, set your source.sourceVersion to 6 or 8. Here are the different parameters available for making the PVWatts call:

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "providerAccountId" : "api-eg-01",
  "providerProfileId" : "PVWATTS_RESIDENTIAL_CA_V8_TESTING",
  "groupBy" : "YEAR",
  "serviceTypes" : "SOLAR_PV",
  "source": {
    "sourceId":"PVWatts",
    "sourceVersion":"8"
  },
  "properties" : {
    "systemSize" : {
      "keyName" : "systemSize",
      "dataValue" : "2.65"
    },
    "azimuth" : {
      "keyName" : "azimuth",
      "dataValue" : "170"
    },
    "losses" : {
      "keyName" : "losses",
      "dataValue" : "15"
    },
    "inverterEfficiency" : {
      "keyName" : "inverterEfficiency",
      "dataValue" : "96"
    },
    "tilt" : {
      "keyName" : "tilt",
      "dataValue" : "17"
    },
    "bifaciality" : {
        "keyName" : "bifaciality",
        "dataValue" : "0.5"
    },
    "albedo" : {
        "keyName" : "albedo",
        "dataValue" : "0.5"
    },
    "useWeatherFileAlbedo" : {
        "keyName" : "useWeatherFileAlbedo",
        "dataValue" : "0"
    },
    "soiling" : {
        "keyName" : "soiling",
        "dataValue" : "12.0, 4.0, 45.0, 23.0, 9.0, 99.0, 67.0, 12.54, 54.0, 9.0, 0.0, 7.6"
    }
  }
}

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "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 - Delete a Usage Profile

You can delete a usage profile at any time. 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:

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’.

1
2
3
4
5
6
7
8
9
{
  "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
  } ]
}