Data Definitions

Usage Profile

Each profile has a unique profileId (a UUID) that Arcadia 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 Arcadia 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 Arcadia maintains to show how up-to-date the profile number crunching is. 1=processing, 2= done, 3=error (we auto-fix 3)
dataFactor	Decimal		Multiplier applied to the readings or baseline values in the profile. (e.g 0.95 = 95%)
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 v6. 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 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	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	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	Either `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 a fixed period of time or interval. These are generated by Arcadia 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
    }
}

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

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)
asTariffTimezone	Boolean	Defaults to false. When true and account tariff is set will return profile readings and intervals in tariff's timezone. If true and account tariff not set, profile will return in UTC. If false the profile will be returned in an internal DST aware UTC variant timezone (current functionality).

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

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 specify `clipBy`, INNER is used. (Optional)
populateReadings	Boolean	When true, the results will contain Reading Data. The default is false. 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.
populateIntervals	Boolean	When true, the results will contain Interval values. The default is false. NOTE: This must be used in concert with the groupBy parameter.
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 or Readings

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 2 - 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 3 - 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 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 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 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.

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

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:

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