Formats

All of our API endpoints are formatted as JSON. Besides the endpoint object formats, we are documenting below the other formats inside these objects you will see.

All API responses are encoded in UTF-8 .

All timestamps in this API are formatted in according to ISO 8601 : YYYY-MM-DDTHH:MM:SS.000000+00:00

For most timestamps on our API (created, revoked, etc.), we use UTC (i.e. +00:00) as the default timezone. However, for timestamps and dates we parse out from utility bills and intervals, we default to the timezone of the utility. So when you see interval data from a utility, it will have the local timezone of the utility in the timestamp so that you can convert it to UTC easily.

When you submit a date/time in a POST request, you need to format it in ISO 8601 format. The separator between the date and time is "T" and the time precision can be down to the microsecond. Here are some examples of valid and invalid ISO8601 formats:

Valid
  • 2014-01-01T01:01:01+00:00
  • 2014-01-01T01:01:01Z
  • 2014-01-01T01:01:01.123456+00:00
  • 2014-01-01T01:01:01.123456Z
  • 2014-01-01T01:01:01.123456-08:00
Invalid
  • 2014-01-01 01:01:01+00:00 (missing "T" separator)
  • 2014-01-01T01:01:01PM (hours are 0-23, not a.m./p.m.)

When you receive HTTP client error response codes ( 4xx ), it indicates that your request contained something we didn't like. We try to tell you exactly what was wrong so that you can fix it and everyone's happy. The error response format contains the following three parameters, but there may also be additional attributes for informational purposes:

  • error - The specific error type.
  • error_description - A human readable description of the error.
  • url - If available, a URL to the docs for more info. Can also be null.
// Example error response
{
    "error": "invalid_param",
    "error_description": "Scope must be a valid json object",
    "url": "https://utilityapi.com/docs/authorization-forms/scopes"
}

This is a success response object on API endpoints that don't return API objects. For example, when you trigger a historical collection, we will simply return this success object with "success": true. There may also be additional attributes for informational purposes.

// Example success objects
{
    "success": true
    ...
}

This is a unique identifier for an API object. This is set by UtilityAPI, not the utility, and is what you use to access specific objects on UtilityAPI. UID strings may look like integers, but don't be fooled! At some point we will likely change them to start including non-digits, so you should always treat them as strings.

// Example UID String
{
    "authorization_uid": "1234",
    ...
}

This is a URL to another endpoint on the API, authorization form, or documentation.

// Example URL
{
    "base_url": "https://utilityapi.com/portal/example_solar",
    ...
}

This is a basic string of text. No really, that's it. Our API uses UTF-8 encoding on all responses, so strings are also encoded in UTF-8. For URL query parameters, be sure to percent encode strings.

// Example string in json
{
    "company_name": "Дcmé Solar, Inc.",
    ...
}
# Example percent encoded string in URL query parameter
https://utilityapi.com/api/v2/authorizations?utility=SDG%26E

This is a binary file that has been Base64 encoded .

// Example encoded png image
{
    "company_logo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==",
    ...
}

This is a basic integer. They are mainly used in utility data blocks.

// Example integer
{
    "level": 2,
    ...
}

This is a basic float. They are mainly used in utility data blocks.

// Example float
{
    "bill_total_volume": 220.01234,
    "bill_total_unit": "kwh",
    ...
}

This is a basic boolean. In json objects they are true and false. In URL query parameters they are the strings "true" and "false".

// Example booleans in json
{
    "is_test": true,
    "is_archived": false,
    ...
}
# Example boolean in URL query parameter
https://utilityapi.com/api/v2/authorizations?is_test=true&is_archived=false

This is a basic null value. In json objects they are null.

// Example null
{
    "next": null,
    ...
}

Whenever we provide a numeric value in a generic field on the API it's usually accompanied by a string indicating the units for that number. We currently support all of the following units and will add to this list as we come across new types of data.

Type Description
kwh Kilowatt hours (e.g. usage)
kw Kilowatts (e.g. demand)
kva Kilovolt-amperes (apparent power)
kvah Kilovolt-ampere-hours (apparent energy)
kvar Reactive Power
kvarh Reactive Energy
therms Natural gas energy (wikipedia)
ccf Gas volume in hundreds of cubic feet
mcf Natural gas energy in thousands of cubic feet
hcf Water volume in hundreds of cubic feet
gallons Water volume in gallons
m3 Water volume in cubic meter
days Days
months Months
percent Percent
poles Number of lamp poles (used in certain Outdoor Lighting Tariffs)
lamps Number of Lamps (used in certain Outdoor Lighting Tariffs)
metering_devices Number of metering devices (e.g. electric meters)
currency Amount of currency (currently only USD is supported)
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

We collect data from many different places and we may use data from multiple sources to compile a full data set. In order to be transparent about where this information comes from, we indicate sources on various types of data and provide links to the raw source files if possible. That way, you can verify that the information parsed from the raw files matches what's in the data provided by the API.

Attribute Format Description Example Utility Gotchas
type SourceType The type of raw source. "pdf"
raw_url URL or null A link to the raw source, if available. "https://utilityapi.com/api/v2/files/abc123abc123"
Additional attributes (for some SourceTypes)
// Source example
{
    "type": "pdf",
    "raw_url": "https://utilityapi.com/api/v2/files/abc123abc123abc123"
}
// Source example with additional attributes
{
    "type": "pdf_other",
    "raw_url": "https://utilityapi.com/api/v2/files/pdf_file_2030_01_04.pdf",
    "format": "nem_details"
}
Type Description Additional Source Attributes
pdf A PDF document, usually containing one or more utility bills or intervals
pdf_other A PDF document other than a utility bill, for example a monthly summary
  • format - String - A utility-specific format type for non-bill PDFs.
raw_pdf A un-parsed PDF document from the utility website
website The HTML of a page on the utility website.
greenbutton_dmd Green Button Download My Data xml files.
greenbutton_cmd Green Button Connect My Data xml files.
greenbutton_other Another form of Green Button xml files.
spreadsheet A spreadsheet download or report.
edi EDI format files.
other Another format we haven't yet categorized.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

Type Description Additional Attributes
cca Energy is supplied by a CCA.
direct_access Energy is purchased directly from an ESP.
third_party Energy is provided by some other third party supplier.