Usage

Our API supports various methods for inputting usage data. The easiest method is by utilizing NREL Building

Profiles. 

NREL Building Profiles

As shown previously in the “Run Your Hotel’s Sample Bill” example, you can choose a building profile from the following list, and our API will automatically fill in the usage

  • FullServiceRestaurant
  • Hospital
  • LargeHotel
  • LargeOffice
  • MediumOffice
  • MidriseApartment
  • OutPatient
  • PrimarySchool
  • QuickServiceRestaurant
  • SecondarySchool
  • SmallHotel
  • SmallOffice
  • Stand-aloneRetail
  • StripMall
  • SuperMarket
  • Warehouse

Uploading Actual Usage

Another way to input usage is to use an actual usage file. The file must be a Comma Separated Value (.csv) file, and must be in the following format to be accepted by our API: mm/dd/yyyy, hh:mm, kWh(usage) (ex. 1/1/2020, 01:00, 2385). As you parse the rows of the usage files, you will need to place each row of data into the hourly_customer_load collection in the payload. From there, sum the hourly usage values and place it into the usage_by_month collection in the usage field. (Note: The perHour collection can be safely left blank for this method.)

Entering Estimated Monthly Usage

The final method that our API supports for inputting estimated usage data, is by entering it manually. For this method, you must fill the usage_by_month collection of the payload, as described below, and ensure that the actual_usage field is false. To fill the perHour collection, divide the usage for that month by the total number of days in the month, and use that value to fill each hour of the month. 

Below we have provided a table showing the fields necessary for our calculation endpoint to run, as well as sample payloads for each form of usage input:

 

Field Name Data Type Description Example
price_node_id Integer Unique Clarity Grid id of the desired price node price_node_id“: 111687,
usage_by_month Collection Collection of monthly usage data

usage_by_month“:

    [

        {

            “startDate“: “2021-11-01”,

            “endDate“: “2021-11-30”,

            “usage“: “9999”,

            “actual_usage“: true,

            “year“: “2021”,

            “month“: “11”,

            “perHour“:

            {

                “2021-11-01 0:00”: 13.8875,

            }

        },

    ],

distributor_id String Unique Clarity Grid id of the Distributor/Utility; Not required by our API distributor_id“: “896”,
distributor_tariff_id String Unique Clarity Grid id of the selected Tariff to run distributor_tariff_id“: “12166”,
latitude Float Latitude of the desired price node; used to determine the best building file to use when using NREL usage latitude“: 30.0907,
longitude Float Longitude of the desired price node; used to determine the best building file to use when using NREL usage longitude“: -95.10646,
hourly_customer_load Collection Collection of hourly load data

hourly_customer_load“:

    {

        “2021-11-1 00:00”: 5.32333333333327,

    },

battery_duration String Used when comparing to a battery (explained further in Analytics) battery_duration“: “”,
building String Name of the desired building type when using NREL usage; types listed above; When not using NREL usage, this field can be safely excluded from the payload building“: “LargeHotel”,
building_from String Beginning of desired time period when using NREL usage; When not using NREL usage, this field can be safely excluded from the payload building_from“: “02/2022”,
building_to String End of desired time period when using NREL usage; When not using NREL usage, this field can be safely excluded from the payload building_to“: “02/2023”

Sample Payload for Building Usage:

Note: The following payload has been heavily condensed, and is solely to show the data structure.

{

    “price_node_id“: 111687,

    “usage_by_month“:

    [],

    “distributor_id“: “”,

    “distributor_tariff_id“: “12166”,

    “latitude“: 0,

    “longitude“: 0,

    “hourly_customer_load“:

    {},

    “battery_duration“: “”,

    “building“: “LargeHotel”,

    “building_from“: “01/2023”,

    “building_to“: “03/2023”

}

Sample Payload for Actual Usage:

Note: The following payload has been heavily condensed, and is solely to show the data structure.

 

{

    “price_node_id“: 111687,

    “usage_by_month“:

    [

        {

            “startDate“: “2021-11-01”,

            “endDate“: “2021-11-30”,

            “usage“: “10010.376881720322”,

            “actual_usage“: true,

            “year“: “2021”,

            “month“: “11”,

            “perHour“:

            {}

        },

    ],

    “distributor_id“: “”,

    “distributor_tariff_id“: “12166”,

    “latitude“: 0,

    “longitude“: 0,

    “hourly_customer_load“:

    {

        “2021-11-01 00:00”: 5.32333333333327,

    },

    “battery_duration“: “”

}

Sample Payload for Estimated Usage:

Note: The following payload has been heavily condensed, and is solely to show the data structure.

{

    “price_node_id“: 111687,

    “usage_by_month“:

    [

        {

            “startDate“: “2023-01-01”,

            “endDate“: “2023-01-31”,

            “usage“: “10000”,

            “actual_usage“: false,

            “year“: “2023”,

            “month“: “01”,

            “perHour“:

            {

                “2023-01-01 00:00”: 13.440860215053762,

            }

        },

    ],

    “distributor_id“: “”,

    “distributor_tariff_id“: “12166”,

    “latitude“: 0,

    “longitude“: 0,

    “hourly_customer_load“:

    {},

    “battery_duration“: “”

}