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

}