Skip Navigation

Our goal is to make UtilityAPI as simple as possible to both use as a website and integrate your apps, tools, platforms, backends, potatoes, etc. Getting utility bill and usage data should be an instant and effortless experience!

This documentation describes how to interact with our API. Below are sections for authorization, data formats, and API endpoints. Hopefully, by the time you're through here, you will have your black-belt in UtilityAPI-fu.


We're dealing with private data here, and we want to make sure it stays that way. We restrict access to data by requiring each request have an api token. This api token must be in every request. You can generate an api token in your user settings.

If you're worried that someone might have stolen one of your api tokens, you can always expire them.

All endpoints require an API token. You can include the API token in either the GET parameter "access_token" or in the Authorization header using Basic or Token formats.


Make a request to get your accounts using an API token in the "access_token" GET parameter: 

curl "https://utilityapi.com/api/accounts.json?access_token=aaaaaaaaaa

Make a request to get your accounts using an API token in Basic Authorization format (note the colon after the token): 

curl -u "aaaaaaaaaa:" "https://utilityapi.com/api/accounts.json"

Make a request to get your accounts using an API token in Token format in the Authorization header (this is just the word "Token" followed by the actual api token): 

curl -H "Authorization: Token aaaaaaaaaa" "https://utilityapi.com/api/accounts.json"

We want the data we collect to be instantly useful to you, so we offer all API endpoints in two formats: json and csv. To request a certain format, you can append the format to url of the request (.json or .csv). Alternatively, you can add an "Accept: application/json" or "Accept: text/csv" header to the request.

Our json format is what we recommend to use if you are integrating UtilityAPI into your own applications. It always has the full object format, so you can see all the data that we have collected for you.

Our csv format is mainly for manual or quick testing and exporting of your data. Since csv data is arranged in a grid, there may be some nested details that cannot be included with this format. Check each endpoint's object format to see what is and isn't included with csv downloads.


All timestamps in this API are formatted in according to ISO 8601:

YYYY-MM-DDTHH:MM:SS.000000+00:00

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 ISO 8601 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

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

Many utility words are super generic, so we try to be very consistent and define our nomeclature. If you get confused, we consider that a bug, so please tell us!

Account: a utility account that has access to Services. Basically, this is the entity that pays the utility bills. For residential users, the account usually only contains one Service (e.g. their home meter). For commercial customers, there can be many Services attached to a single Account (e.g. multiple office building meters).

Service: a utility service that has electric usage history. Basically, this is the thing that has a utility meter. We didn't call it a Meter because utilities often replace meters without changing the Service. Also utilities usually call it "service", so we're calling it that, too. We try not to call anything a "meter" (except the actual meter_number) to avoid confusion. We currently don't support gas or water services, so for now it is assumed that a Service is for an electricity service.

Tariff: the utility rate schedule that a Service is on. This is a piece of information we include when collecting utility data, but it can be called "rate" or "rate schedule". We are going to always refer to it as Tariff and avoid using the term "rate" to avoid confusion.

Bill: the invoice charging for Service use. This is one of the two pieces of data we collect. Even if you receive one paper bill for multiple services, we automatically break the bill apart and include the appropriate subset under each Service.

Interval: electricity use for a certain time period. This is the other of the two pieces of data we collect. With the advent of smart meters, the utility can collect energy usage over small increments. When this is available, we will collect it as a download option.

User: the entity using UtilityAPI. Users can add, modify, and remove Accounts, Services, and Tokens. We try not to refer to User's settings as "account settings" to avoid confusion with Accounts added by the user.

uid: the unique identifier for the UtilityAPI object. This is set by UtilityAPI, not the utility, and is what you use to access specific objects on UtilityAPI. In API endpoint requests and responses, these will always appear as something_uid to avoid confusion with another field that has information about some utility identifier.

id: an identifier NOT set by UtilityAPI. This is different from the above <uid>. The most visible example of this is "service_uid" vs. "utility_service_id". The former is what you use to retrieve the Service object from /services/<uid>, and the later is the utility's assigned service identifier. We wish we could have just used the utility's service id as the uid, but since we work with multiple utilities, we don't want to risk a conflicting service identifier between different utilities.

SAID: An abbreviation for utility_service_id that is used in some website tables and documentation.


In general, we try to always give you the most up-to-date information. Even if we are the middle of collecting data for a new object, you can still request all the data that we've collected so far. That way, you can start doing the stuff you need to do as soon as possible.

We do not limit the quantity of data that you can download in one request (it's your data after all). We also try not to limit the number of times you download your data. However, if you are spamming downloads that's putting a burden on our servers, we may rate limit how many times you can request that data per hour.

As a general rule, please try to not GET request bill and interval downloads more than once per minute, and all other GET and POST requests once per second. If you need more throughput than that, please let us know and we will work with you to make it happen!


There are eight major objects that we use: Accounts, Services, Bills, Intervals, Users, Tokens, Logs, and Docs. There are json and csv formats for each object type, which are specified below.

All fields listed below should always be included in each object. If a field for an object format is not included in the object, the field is still pending collection. This mostly happens in the Service, Bill, and Interval objects, where those objects are saved progressively as they are collected. If a field has been collected but there is no value, the field will appear in the object with a value of null (for json) or empty string (for csv).

Field descriptions below contain the key name, value format, and description. For each object there is also an example object showing what a typical object will look like.


This is the object representing utility accounts. This object contains the customer authorization and access credentials for the utility account.


  • uid - String - The unique identifier of the object. Account uids are mostly integers, but they are not guaranteed to stay that way, so you should treat them as strings.

  • user_uid - String - The unique identifier of the User that created the Account. User uids are mostly integers, but they are not guaranteed to stay that way, so you should treat them as strings.

  • utility - String - The utility abbreviation. Will be one of "DEMO", "PG&E", "SCE", or "SDG&E".

  • created - ISO8601 - A timestamp from when the object was created.

  • auth_type - String - The type of authorization submitted. Can be either "owner" or "3rdparty".

  • auth - String - Details about the authorizer. If the auth_type is "owner", then this field is the customer signature giving UtilityAPI authorization to access their utility account on their behalf. If the auth_type is "3rdparty", then this field is a link to the submitted 3rd party customer authorization form giving 3rd party authorization to access the utility account. NOTE: Always check the auth_type before using the link in this field. A malicious person could have put in a bogus link as their real name, so don't just check this field to see if it starts with http. If you are stubborn and insist on not checking the auth_type field, at least make sure you test that this field starts with "https://utilityapi.com/" before making it a link.

  • auth_expires - ISO8601 - A timestamp from when the customer authorization expires.

  • login - String - The type of access to that is used to collect the data. So far, this can be "credentials" or "account_number", but in the future we may add more access methods (for example, Green Button Connect).

  • latest - Log - The latest log message for service access of the account. This is what you check to see if the Account is currently looking for Services (i.e. "pending"), has finished (i.e. "updated"), or raised an error (i.e. "error"). See the examples to see what these can look like. Not included in csv format.


John Doe adds his own utility account via the widget, and the Account has finished updating the list of Services: 

{
    "uid": "12345",
    "user_uid": "42",
    "utility": "PG&E",
    "created": "2014-06-17T16:04:34.023534+00:00",
    "auth_type": "owner",
    "auth": "John Doe",
    "auth_expires": "2015-06-17T16:04:34.023534+00:00",
    "login": "credentials",
    "latest": {
        "type": "updated",
        "message": "Services refreshed",
        "timestamp": "2014-06-17T16:06:34.473724+00:00",
    }
}

John Doe adds his own utility account via the widget, but the Account encountered an error with his submitted login credentials: 

{
    "uid": "12345",
    "user_uid": "42",
    "utility": "PG&E",
    "created": "2014-06-17T16:04:34.023534+00:00",
    "auth_type": "owner",
    "auth": "John Doe",
    "auth_expires": "2015-06-17T16:04:34.023534+00:00",
    "login": "credentials",
    "latest": {
        "type": "error",
        "message": "Login credentials don't seem to work.",
        "timestamp": "2014-06-17T16:05:34.473724+00:00",
    }
}

A 3rd Party has authorization from John Doe to access his utility account, and the Account is currently looking for Services: 

{
    "uid": "12346",
    "user_uid": "42",
    "utility": "PG&E",
    "created": "2014-06-22T09:14:34.463265+00:00",
    "auth_type": "3rdparty",
    "auth": "https://utilityapi.com/accounts/12346/auth.zip",
    "auth_expires": "2015-06-22T09:14:34.463265+00:00",
    "login": "credentials",
    "latest": {
        "type": "pending",
        "message": "Parsing 1 of 2 services...",
        "timestamp": "2014-06-23T10:12:03.483722+00:00",
    }
}

This is the object representing utility services. This object contains metadata on the service such as meter number, tariff, etc.


  • uid - String - The unique identifier of the object. Service uids are mostly integers, but they are not guaranteed to stay that way, so you should treat them as strings. NOTE: This is specific to UtilityAPI, not the utility. The utility's identifier for a service is found in the utility_service_id field.

  • user_uid - String - The unique identifier of the User that created the Account to which this Service belongs. If you request the Account object, the user_uid field in that object will be the same as this value.

  • account_uid - String - The unique identifier of the Account object to which this Service belongs.

  • account_auth_type - String - The type of authorization submitted. Can be either "owner" or "3rdparty". This is the same field as the Account auth_type field.

  • account_auth - String - Details about the authorizer. This contains either a customer signature giving UtilityAPI authorization to access their utility account on their behalf, or a link to the submitted 3rd party customer authorization form giving 3rd party authorization to access the utility account. This is the same field as the Account auth field.

  • utility - String - The utility abbreviation. Will be one of "DEMO", "PG&E", "SCE", or "SDG&E". This field is denormalized from the Account object for convenience.

  • created - ISO8601 - A timestamp from when the object was created.

  • active_until - ISO8601 - A timestamp for when to stop monitoring this service for updates. This cannot be set to a date/time after the parent Account auth_expires value.

  • latest - Log - The latest log message for data collection of the service. This is what you check to see if the Service is currently looking for bills and intervals (i.e. "pending"), has finished (i.e. "updated"), or raised an error (i.e. "error"). See the examples to see what these can look like. Not included in csv format.

  • utility_service_id - String - The utility's service identifier. The format of this is different for each utility (may contain dashes, spaces, etc.).

  • utility_tariff_name - String - The current utility tariff (i.e. rate schedule) for the service. May not be included if Account is still looking up Services

  • utility_service_address - String - The service address for the service. This is what the utility uses and may not be an address you can use to search for the address on an online map. We may add another field with a mappable address at some point in the future, so please let us if that would be valuable to you. May not be included if Account is still looking up Services

  • utility_billing_account - String - The billing account id for the service. This may or may not be different from the utility_service_id. The format of this is different for each utility (may contain dashes, spaces, etc.). May not be included if Account is still looking up Services

  • utility_billing_contact - String - The billing contact name for the service. The format of this is different for each utility (may contain dashes, spaces, etc.). May not be included if Account is still looking up Services

  • utility_billing_address - String - The billing address for the service (i.e. where the bills are sent). May not be included if Account is still looking up Services

  • utility_meter_number - String - The current meter number for the physical meter on the service. Some utilities may use the same number for both the utility_service_id and the utility_meter_number, but many utilities have different numbers for these fields (which is why we list them separately). May not be included if Account is still looking up Services

  • bill_coverage - Array - A list of date ranges that are covered by collected bills. A date range is a two-item array with a start and end date formatted in ISO8601. If we have a complete history of bills, there will be only one date range in this array. If there is are some missing bills, the date ranges will only show the coverage that is covered by the collected bills. If no bills have been collected, this array will be empty. This field can be useful in checking to see if the Service meets your coverage requirements.

  • bill_count - Integer - The number of bills that have been collected and parsed. This number should match the length of the list returned by the /services/<uid>/bills request.

  • inteval_coverage - Array - A list of date ranges that are covered by collected intervals. A date range is a two-item array with a start and end date formatted in ISO8601. If we have a complete history of intervals, there will be only one date range in this array. If there is are some missing intervals, the date ranges will only show the coverage that is covered by the collected intervals. If no intervals have been collected, this array will be empty. This field can be useful in checking to see if the Service meets your coverage requirements.

  • interval_count - Integer - The number of intervals that have been collected and parsed. This number should match the length of the list returned by the /services/<uid>/intervals request.


John Doe's utility service, which has two complete years of bill and interval history: 

{
    "uid": "45678",
    "user_uid": "42",
    "account_uid": "12345",
    "utility": "PG&E",
    "created": "2014-06-17T16:04:34.023534+00:00",
    "active_until": "2015-06-17T16:04:34.023534+00:00",
    "latest": {
        "type": "updated",
        "message": "Data refreshed",
        "timestamp": "2014-06-17T16:06:34.473724+00:00",
    },
    "utility_service_id": "5555555-5",
    "utility_tariff_name": "A6-TOU",
    "utility_billing_account": "999999999-9",
    "utility_billing_address": "123 MAIN ST",
    "utility_billing_contact": "SMITH,JOHN",
    "utility_service_address": "123 MAIN ST",
    "utility_meter_number": "11111-1111-11",
    "bill_coverage": [
        [
            "2012-01-05T07:00:00.000000+00:00",
            "2014-01-10T07:00:00.000000+00:00",
        ],
    ],
    "bill_count": 25,
    "interval_coverage": [
        [
            "2012-01-05T07:00:00.000000+00:00",
            "2014-01-18T07:00:00.000000+00:00",
        ],
    ],
    "interval_count": 17832,
}

John Doe's utility service while the Service is in the middle of collecting bill and interval data (has found some bills but no intervals so far). 

{
    "uid": "45678",
    "user_uid": "42",
    "account_uid": "12345",
    "utility": "PG&E",
    "created": "2014-06-17T16:04:34.023534+00:00",
    "active_until": "2015-06-17T16:04:34.023534+00:00",
    "latest": {
        "type": "pending",
        "message": "Downloading bill 4/25...",
        "timestamp": "2014-06-17T16:06:34.473724+00:00",
    },
    "utility_service_id": "5555555-5",
    "utility_tariff_name": "A6-TOU",
    "utility_billing_account": "999999999-9",
    "utility_billing_address": "123 MAIN ST",
    "utility_billing_contact": "SMITH,JOHN",
    "utility_service_address": "123 MAIN ST",
    "utility_meter_number": "11111-1111-
    "bill_coverage": [
        [
            "2012-01-05T07:00:00.000000+00:00",
            "2012-03-06T07:00:00.000000+00:00",
        ],
        [
            "2013-05-05T07:00:00.000000+00:00",
            "2013-06-02T07:00:00.000000+00:00",
        ],
    ],
    "bill_count": 3,
    "interval_coverage": [],
    "interval_count": 0,
}

This is the object representing utility bill. This object contains bill data, including usage and pricing.


  • service_uid - String - The unique identifier of the Service object to which this bill object belongs. NOTE: There is no unique identifier for individual bills since they are only accessible via the /services/<uid>/bills.

  • utility - String - The utility abbreviation. Will be one of "DEMO", "PG&E", "SCE", or "SDG&E". This field is denormalized from the Account object for convenience.

  • utility_service_id - String - The utility's service identifier. This field may be different from different from the parent Service's utility_service_id if the service changed for the same location (e.g. if the customer switched tariffs when they bought an electric vehicle or signed up for a demand response program). We try to include past utility_service_ids so you can have a more complete bill history for a utility service.

  • utility_tariff_name - String - The bill's utility tariff (i.e. rate schedule) for the service. This field may be different from different from the parent Service's utility_tariff_name if the service tariff changed for the same location (e.g. if the customer switched tariffs when they bought an electric vehicle or signed up for a demand response program). We try to include past utility_tariff_names so you can have a more complete understanding of the customer's billing history and usage.

  • utility_service_address - String - The bill's service address for the meter. This field may be different from different from the parent Service's utility_service_address if the service address changed (e.g. if the utility swapped out meters and updated the format of the service address). We try to include past utility_service_addresss so you can have a more complete understanding of the bill history for the same service.

  • utility_meter_number - String - The bill's meter number for the service. This field may be different from different from the parent Service's utility_meter_number if the meter changed (e.g. if the utility swapped out an analog meter for a smart meter). We try to include past utility_meter_numbers so you can have a more complete understanding of the bill history for the same service.

  • bill_start_date - ISO8601 - The start date of the billing period for the service.

  • bill_end_date - ISO8601 - The end date of the billing period for the service.

  • bill_bill_days - Integer - The total number of days between the start and end dates of the billing period for the service.

  • bill_statement_date - ISO8601 - The date that the bill stated was issued.

  • bill_total_kWh - Float - The total energy usage (in kilowatt hours) during the billing period for the service.

  • bill_total - Float - The bill charges (in dollars) for electricity usage during the billing period.

  • bill_breakdown - Object - A breakdown of the individual charges contributing to the bill_total amount. This is an arbitrary json object that may include lists or other json objects. We try to include relevant data to the bill such as a line item breakdown, demand charge breakdown, and/or time of use breakdown. This structure varies from utility to utility because the tariff structure varies widely. If you want more specifics, contact us at info@utilityapi.com. Not included in csv format.

  • source - String - The location where the bill data was collected. If the source is available for download (e.g. a pdf bill), a link is provided here. If the source is not available for download (e.g. data collected from the utility's web portal), this field is left blank.

  • updated - ISO8601 - When the bill data was last updated.


John Doe's bill history (2 bills): 

[
    {
        "bill_bill_days": 30,
        "bill_breakdown": {
            "line_items": [
                {
                    "cost": 52.88,
                    "end": "2015-02-05T08:00:00.000000+00:00",
                    "name": "Tier 1 Usage",
                    "rate": 0.1617,
                    "start": "2015-01-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 327.0
                },
                {
                    "cost": 18.14,
                    "end": "2015-02-05T08:00:00.000000+00:00",
                    "name": "Tier 2 Usage",
                    "rate": 0.18491,
                    "start": "2015-01-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 98.1
                },
                {
                    "cost": 62.54,
                    "end": "2015-02-05T08:00:00.000000+00:00",
                    "name": "Tier 3 Usage",
                    "rate": 0.27322,
                    "start": "2015-01-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 228.9
                },
                {
                    "cost": 60.98,
                    "end": "2015-02-05T08:00:00.000000+00:00",
                    "name": "Tier 4 Usage",
                    "rate": 0.33322,
                    "start": "2015-01-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 183.0
                },
                {
                    "cost": 0.24,
                    "end": "2015-02-05T08:00:00.000000+00:00",
                    "name": "Energy Commission Tax",
                    "rate": null,
                    "start": "2015-01-07T08:00:00.000000+00:00",
                    "unit": null,
                    "volume": null
                }
            ],
            "tiers": {
                "Tier 1 ($)": 52.88,
                "Tier 1 (kWh)": 327.0,
                "Tier 2 ($)": 18.14,
                "Tier 2 (kWh)": 98.1,
                "Tier 3 ($)": 62.54,
                "Tier 3 (kWh)": 228.9,
                "Tier 4 ($)": 60.98,
                "Tier 4 (kWh)": 183.0
            }
        },
        "bill_end_date": "2015-02-05T08:00:00.000000+00:00",
        "bill_start_date": "2015-01-07T08:00:00.000000+00:00",
        "bill_statement_date": "2015-02-06T08:00:00.000000+00:00",
        "bill_total": 194.78,
        "bill_total_kWh": 837.0,
        "service_uid": "58",
        "source": "http://localhost:8000/api/services/58/bills/1234567890_2015-01-07_to_2015-02-05.pdf",
        "updated": "2015-03-19T20:50:41.206253+00:00",
        "utility": "DEMO",
        "utility_meter_number": "A987654321",
        "utility_service_address": "123 Main St #100, Anytown, CA 94612",
        "utility_service_id": "1234567890",
        "utility_tariff_name": "E1 XB Residential Service"
    },
    {
        "bill_bill_days": 31,
        "bill_breakdown": {
            "line_items": [
                {
                    "cost": 41.67,
                    "end": "2014-12-31T08:00:00.000000+00:00",
                    "name": "Tier 1 Usage",
                    "rate": 0.15293,
                    "start": "2014-12-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 272.5
                },
                {
                    "cost": 14.4,
                    "end": "2014-12-31T08:00:00.000000+00:00",
                    "name": "Tier 2 Usage",
                    "rate": 0.17614,
                    "start": "2014-12-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 81.75
                },
                {
                    "cost": 50.44,
                    "end": "2014-12-31T08:00:00.000000+00:00",
                    "name": "Tier 3 Usage",
                    "rate": 0.26445,
                    "start": "2014-12-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 190.75
                },
                {
                    "cost": 89.28,
                    "end": "2014-12-31T08:00:00.000000+00:00",
                    "name": "Tier 4 Usage",
                    "rate": 0.32445,
                    "start": "2014-12-07T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 275.16129
                },
                {
                    "cost": 0.24,
                    "end": "2014-12-31T08:00:00.000000+00:00",
                    "name": "Energy Commission Tax",
                    "rate": null,
                    "start": "2014-12-07T08:00:00.000000+00:00",
                    "unit": null,
                    "volume": null
                },
                {
                    "cost": 10.58,
                    "end": "2015-01-06T08:00:00.000000+00:00",
                    "name": "Tier 1 Usage",
                    "rate": 0.1617,
                    "start": "2015-01-01T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 65.4
                },
                {
                    "cost": 3.63,
                    "end": "2015-01-06T08:00:00.000000+00:00",
                    "name": "Tier 2 Usage",
                    "rate": 0.18491,
                    "start": "2015-01-01T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 19.62
                },
                {
                    "cost": 12.51,
                    "end": "2015-01-06T08:00:00.000000+00:00",
                    "name": "Tier 3 Usage",
                    "rate": 0.27322,
                    "start": "2015-01-01T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 45.78
                },
                {
                    "cost": 22.01,
                    "end": "2015-01-06T08:00:00.000000+00:00",
                    "name": "Tier 4 Usage",
                    "rate": 0.33322,
                    "start": "2015-01-01T08:00:00.000000+00:00",
                    "unit": "kWh",
                    "volume": 66.03871
                },
                {
                    "cost": 0.06,
                    "end": "2015-01-06T08:00:00.000000+00:00",
                    "name": "Energy Commission Tax",
                    "rate": null,
                    "start": "2015-01-01T08:00:00.000000+00:00",
                    "unit": null,
                    "volume": null
                }
            ],
            "tiers": {
                "Tier 1 ($)": 52.25,
                "Tier 1 (kWh)": 337.9,
                "Tier 2 ($)": 18.03,
                "Tier 2 (kWh)": 101.37,
                "Tier 3 ($)": 62.949999999999996,
                "Tier 3 (kWh)": 236.53,
                "Tier 4 ($)": 111.29,
                "Tier 4 (kWh)": 341.2
            }
        },
        "bill_end_date": "2015-01-06T08:00:00.000000+00:00",
        "bill_start_date": "2014-12-07T08:00:00.000000+00:00",
        "bill_statement_date": "2015-01-07T08:00:00.000000+00:00",
        "bill_total": 244.82,
        "bill_total_kWh": 1017.0,
        "service_uid": "58",
        "source": "http://localhost:8000/api/services/58/bills/1234567890_2014-12-07_to_2015-01-06.pdf",
        "updated": "2015-03-19T20:50:42.215191+00:00",
        "utility": "DEMO",
        "utility_meter_number": "A987654321",
        "utility_service_address": "123 Main St #100, Anytown, CA 94612",
        "utility_service_id": "1234567890",
        "utility_tariff_name": "E1 XB Residential Service"
    }
]

This is the object representing a meter interval. This object contains interval data, including usage and demand.

NOTE: Often, if a service tariff or meter has been changed, the utility will no longer provide the interval data before the change. We will try our best to collect all historical interval data, but we are limited by what is made available by the utility.


  • service_uid - String - The unique identifier of the Service object to which this interval object belongs. NOTE: There is no unique identifier for individual intervals since they are only accessible via the /services/<uid>/intervals.

  • utility - String - The utility abbreviation. Will be one of "DEMO", "PG&E", "SCE", or "SDG&E". This field is denormalized from the Account object for convenience.

  • utility_service_id - String - The utility's service identifier. This field may be different from the parent Service's utility_service_id if the service changed for the same location (e.g. if the customer switched tariffs when they bought an electric vehicle or signed up for a demand response program). We try to include past utility_service_ids so you can have a more complete interval history for a utility service.

  • utility_tariff_name - String - The interval's utility tariff (i.e. rate schedule) for the service. This field may be different from different from the parent Service's utility_tariff_name if the service tariff changed for the same location (e.g. if the customer switched tariffs when they bought an electric vehicle or signed up for a demand response program). We try to include past utility_tariff_names so you can have a more complete understanding of the customer's interval history.

  • utility_service_address - String - The interval's service address for the meter. This field may be different from different from the parent Service's utility_service_address if the service address changed (e.g. if the utility swapped out meters and updated the format of the service address). We try to include past utility_service_addresss so you can have a more complete understanding of the interval history for the same service.

  • utility_meter_number - String - The interval's meter number for the service. This field may be different from different from the parent Service's utility_meter_number if the meter changed (e.g. if the utility swapped out an analog meter for a smart meter). We try to include past utility_meter_numbers so you can have a more complete understanding of the interval history for the same service.

  • interval_start - ISO8601 - The start timestamp of the interval period.

  • interval_end - ISO8601 - The end timestamp of the interval period.

  • interval_kWh - Float - The total energy usage (in kilowatt hours) during the interval period.

  • interval_kW - Float - The total demand (in kilowatts) during the interval period. This is a simple calculation of the usage divided by the time period. NOTE: For demand charges, the demand interval period might be shorter than what is provided in these intervals (i.e. if the demand is calculated for a 15 interval, but we can only collect hour intervals), so you may not be able to confirm the demand charge on the bill just from this interval data :(

  • source - String - The location where the interval data was collected. If the source is available for download (e.g. a zip file), a link is provided here. If the source is not available for download (e.g. data collected from the utility's web portal), this field is left blank.

  • updated - ISO8601 - When the interval data was last updated.


John Doe's interval history (2 intervals): 

[
    {
        "service_uid": "45678",
        "utility": "PG&E",
        "utility_service_id": "5555555-5",
        "utility_tariff_name": "E10-TOU",
        "utility_service_address": "123 MAIN ST",
        "utility_meter_number": "11111-1111-11",
        "interval_start": "2012-01-05T07:00:00.000000+00:00",
        "interval_end": "2012-01-05T07:15:00.000000+00:00",
        "interval_kWh": 1.25,
        "interval_kW": 5.0,
        "source": "https://utilityapi.com/services/45678/intervals/2012.zip",
        "updated": "2014-06-17T16:06:34.473724+00:00",
    },
    {
        "service_uid": "45678",
        "utility": "PG&E",
        "utility_service_id": "5555555-5",
        "utility_tariff_name": "E10-TOU",
        "utility_service_address": "123 MAIN ST",
        "utility_meter_number": "11111-1111-11",
        "interval_start": "2012-01-05T07:15:00.000000+00:00",
        "interval_end": "2012-01-05T07:30:00.000000+00:00",
        "interval_kWh": 1.5,
        "interval_kW": 6.0,
        "source": "https://utilityapi.com/services/45678/intervals/2012.zip",
        "updated": "2014-06-17T16:06:34.533265+00:00",
    },
]

This is the object representing a UtilityAPI user.


  • uid - String - The unique identifier of the object. User uids are mostly integers, but they are not guaranteed to stay that way, so you should treat them as strings.

  • email - String - The user's email address.

  • password - String - Will always be "**". We hash and salt User passwords, so we have no idea what your password is (hence why you can only reset your password).

  • created - ISO8601 - A timestamp from when the user was created.


John Doe's user object:

{
    "uid": "1337",
    "email": "john.doe@example.com",
    "password": "****",
    "created": "2014-06-05T09:34:45.749632+00:00",
}

This is the object representing a UtilityAPI token. There are several types of tokens, but they are all in the same object format.


  • uid - String - The unique identifier of the object. Token uids are mostly lowercase hex values, but they are not guaranteed to stay that way, so you should treat them as strings.

  • type - String - The type of token. This will be one of "api", "widget", or "referral". Api tokens are what you use to send requests to API endpoints. Widget tokens are what you used when embedding a widget. Referral tokens are what you use to refer users using our affiliate program (these can only currently be created manually, so please ask us if you want to have a referral token).

  • created - ISO8601 - A timestamp from when the token was created.

  • expires - ISO8601 - A timestamp from when the token expires.

  • user_uid - String - The unique identifier of the user who owns the token.

  • request_count - Integer - The number of requests performed using this token. Only used for api tokens.

  • signup_count - Integer - The number of users created via this token. Only used for widget and referral tokens.


John Doe's api token: 

{
    "uid": "085129c2319846fa898f2b9ba824e61b",
    "type": "api",
    "created": "2014-06-05T09:34:45.749632+00:00",
    "expires": "2024-06-05T09:34:45.749632+00:00",
    "user_uid": "1337",
    "request_count": 58008,
    "signup_count": 0
}

This is the object representing a UtilityAPI log entry.

This is the object representing a UtilityAPI log entry. These are used as values for the latest logs on several other objects, as well as in list form for token usage histories.


  • type - String - The log entry type. One of "updated", "error", or "pending". Updated logs indicate a successfully finished task. Error logs indicate a task that finished with an error. Pending logs indicate that a task is still ongoing.

  • timestamp - ISO8601 - The timestamp of the log entry.

  • message - String - The message of the log entry. These may change, so don't rely on their syntax.


A log entry that shows no changes: 

{
    "type": "updated",
    "message": "No modifications since creation.",
    "timestamp": "2014-06-05T09:34:45.749632+00:00",
}

A log entry that shows an error: 

{
    "type": "error",
    "message": "Login credentials don't seem to work.",
    "timestamp": "2014-06-17T16:05:34.473724+00:00",
}

A log entry that shows the task is still pending: 

{
    "type": "pending",
    "message": "Parsing 1 of 2 services...",
    "timestamp": "2014-06-23T10:12:03.483722+00:00",
}

This is the object representing a UtilityAPI documentation object. This is only used in for documentation, so you won't see this anywhere in the official API endpoints. But we're all about documentation, and you can download docs in json format, so we figure we'd include the object format for completeness.


  • type - String - The type of documentation object. Currently, "section" is the only type. We may add more object types.

  • title - String - The heading title of the documentation section. This may not be included with other doc types (when and if we add them).

  • anchor - String - The deeplink to that particular object within the page. This is used by our html renderer to allow linking to a particular section of the documentation.

  • contents - List - A list of strings or doc objects that are children of the current doc object. Strings in this list are formatted with markdown.


A simple documentation object: 

{
    "type": "section",
    "title": "Test Post",
    "anchor": "post",
    "contents": [
        "please ignore",
        {
            "type": "section",
            "title": "Comments",
            "anchor": "comments",
            "contents": [
                "Don't tell me what to do! Upvoted.",
                "Test comment, please ignore",
            ],
        }
    ],
}

These are the endpoints available in the API. We try to be as RESTful as possible, so that you can easily integrate UtilityAPI into your workflow. Our biggest departure from REST is that we only use GET and POST methods. Instead of having PUT, DELETE, and UPDATE options, we have added special POST endpoints for each object that performs the action on the object. This is because our web interface heavily uses HTML forms (which only allow GET and POST), and we want to dogfood our API.



Return a list of Account objects that you have permission to see.


Not used. If you want to add an account, use /accounts/add. If you want to modify an account, use /accounts/<uid>/modify. If you want to delete an account and all of its services (and each service's associated bill and interval data), use /accounts/<uid>/delete.



Returns the requirements for creating a new account. This is most often used by the website to build the account adding form.


An example list of utilities with their authorization requirements: 

curl -u "aaaaaaaaaa:" https://utilityapi.com/api/accounts/add.json
{
    "help": "...",
    "docs": "https://utilityapi.com/...",
    "options": [
        {
            "utility": "DEMO",
            "name": "Demo (username: test, password: test)",
            "allows": ["owner", "3rdparty"],
            "options": [
                [
                    {
                        "name": "utility_username",
                        "type": "text",
                        "help": "The login username for the utility account",
                    },
                    {
                        "name": "utility_password",
                        "type": "text",
                        "help": "The login password for the utility account",
                    }
                ]
            ]
        },
        {
            "utility": "PG&E",
            "name": "Pacific Gas and Electric (PG&E)",
            "allows": ["owner", "3rdparty"],
            "options": [
                [
                    {
                        "name": "utility_username",
                        "type": "text",
                        "help": "The login username for the utility account",
                    },
                    {
                        "name": "utility_password",
                        "type": "text",
                        "help": "The login password for the utility account",
                    }
                ]
            ]
        },
        {
            "utility": "SCE",
            "name": "Southern California Edison (SCE)",
            "allows": ["owner", "3rdparty"],
            "options": [
                [
                    {
                        "name": "utility_username",
                        "type": "text",
                        "help": "The login username for the utility account",
                    },
                    {
                        "name": "utility_password",
                        "type": "text",
                        "help": "The login password for the utility account",
                    }
                ]
            ]
        },
        {
            "utility": "SDG&E",
            "name": "San Diego Gas and Electric (SDG&E)",
            "allows": ["owner", "3rdparty"],
            "options": [
                [
                    {
                        "name": "utility_username",
                        "type": "text",
                        "help": "The login username for the utility account",
                    },
                    {
                        "name": "utility_password",
                        "type": "text",
                        "help": "The login password for the utility account",
                    }
                ]
            ]
        }
    ]
}

Adds a new account with the submitted utility authorization and access information. This creates a new Account object on UtilityAPI and returns the newly created Account object.


  • utility - String - One of the utilities that are listed in GET /accounts/add. The current options are "DEMO", "PG&E", "SCE", and "SDG&E". This is required for all POST /accounts/add requests.

  • auth_type - String - The type of customer customer authorization. Can be either "owner" or "3rdparty". This is required for all POST /accounts/add requests.

  • real_name - String - The full name of the customer giving direct authorization. This is the digital signature of the owner of the utility account. If the auth-type is "owner", this field is required.

  • 3rdparty_file - Base64 - A base64 encoded string of a completed utility authorization form filled out and signed by the owner of the utility account. If the auth-type is "3rdparty", this field is required.

  • utility_username - String - The login username of the utility account that the customer is authorizing access to. This is one of the fields that is in the access options.

  • utility_password - String - The login password of the utility account that the customer is authorizing access to. This is one of the fields that is in the access options.


Adding a Demo account: 

curl -X POST -u "aaaaaaaaaa:" \
    -H "Content-Type: application/json" \
    -d '{"utility": "DEMO", "auth_type": "owner", "real_name": "John Doe", "utility_username": "test", "utility_password": "test"}' \
    "https://utilityapi.com/api/accounts/add.json"
{
    "uid": "12345",
    "user_uid": "42",
    "utility": "PG&E",
    "created": "2014-06-17T16:04:34.023534+00:00",
    "auth_type": "owner",
    "auth": "John Doe",
    "auth_expires": "2015-06-17T16:04:34.023534+00:00",
    "login": "credentials",
    "latest": {
        "type": "updated",
        "message": "Services refreshed",
        "timestamp": "2014-06-17T16:06:34.473724+00:00",
    }
}


Returns an account object. Currently, you can only request accounts that you have added. In future updates, we may start to allow requests of other accounts objects if their owners have authorized you to see them.


Not implemented. If you want to add a account, use /accounts/add. If you want to modify a service, use /services/<uid>/modify.



Returns the requirements for modifying an existing account. This is most often used by the website to build the account modification form.


Modifies an account object. This is commonly used when utility login credentials need to be updated. To forget the login credentials, modify the utility username and password to gibberish, and the old login credentials will be forgotten. By default, this will trigger all active services that belong to the account to update their bill and interval datasets.


  • auth_type - String - optional - The type of authorization used. Will be either 'owner' or '3rdparty'. Using 'owner' indicates that you are the owner of the utility account and requires the parameter real_name to be posted as well; '3rdparty' indicates you have an authorization form which you must upload in the 3rdparty_file parameter.

  • real_name - String - optional - The full name of the customer giving direct authorization. This is the digital signature of the owner of the utility account. If the auth_type is "owner", this field is required.

  • 3rdparty_file - Base64 - optional - A base64 encoded string of a completed utility authorization form filled out and signed by the owner of the utility account. If the auth_type is "3rdparty", this field is required.

  • utility_username - String - optional - The login username of the utility account that the customer is authorizing access to. Must be posted in conjunction with utility_password.

  • utility_password - String - optional - The login password of the utility account that the customer is authorizing access to. Must be posted in conjunction with utility_username.

  • update_services - Boolean - optional - By default, when you POST to this endpoint, we will automatically re-collect the services for this account. If you don't want this to happen, set update_services to false when you POST to this endpoint.

  • update_data - Boolean - optional - By default, when you POST to this endpoint, we will automatically re-collect the service data for services in this account if their active_until time is in the future. If you don't want this to happen, set update_data to false when you POST to this endpoint.



Returns the requirements for deleting an existing account. This is request contains a server-signed confirmation code that must be submitted with the POST call at this endpoint. The confirmation code is mostly to prevent you from accidentally deleting an object.


Deletes an account object. NOTE: THIS IS A CASCADE EVENT! All services that belong to that account will also be deleted, and all bills and intervals that belong those services will also be deleted! This request requires a signed confirmation code obtained by making a GET request to this endpoint.


  • code - String - A confirmation code which allows you to delete your account. To acquire a valid code, perform a GET request to this endpoint.


Return a list of service objects that you have permission to see.


Not used. If you want to activate a service, change the active_until date to a future date using /services/<uid>/modify. If you want to deactivate a service, change the active_until date to the past using /services/<uid>/modify. If you want to reset a service and delete its bill and interval data, use /services/<uid>/reset.



Returns a service object. Currently, you can only request services that you have added. In future updates, we may start to allow requests of other service objects if their owners have authorized you to see them.


Not used. If you want to activate a service, change the active_until date to a future date using /services/<uid>/modify. If you want to deactivate a service, change the active_until date to the past using /services/<uid>/modify. If you want to reset a service and delete its bill and interval data, use /services/<uid>/reset.



Returns a list of bill objects for this service. This is the request you make to get the bill history of a service.


Not used. To remove the billing history for a service, use /services/<uid>/reset.



Returns a list of interval objects for this service. This is the request you make to get the interval history of a service.


  • start - ISO8601 - optional - A start cutoff for the intervals. This can also be an ISO date (YYYY-MM-DD), which will assume midnight UTC as the time for that date.

  • end - ISO8601 - optional - A end cutoff for the intervals. This can also be an ISO date (YYYY-MM-DD), which will assume midnight UTC as the time for that date.


Not used. To remove the interval history for a service, use /services/<uid>/reset.



Returns the requirements for modifying an existing service. This is most often used by the website to build the service modification form.


Modifies a service object. This is commonly used when activating or deactivating the service by changing the active_until date to a past date. By default, bills and intervals for the service are updated after the service has been modified.


  • active_until - ISO8601 or String - optional - If the time is in the past, the service is considered inactive and data will not be collected. If the time is in the future, data will be collected periodically until that time. If you POST a value of "now", the time will be set to the current time and the data will be collected only once.

  • update_data - Boolean - optional - By default, when you POST to this endpoint, we will automatically re-collect the service data if the active_until time is in the future. If you don't want this to happen, set update_data to false when you POST to this endpoint.



Returns the requirements for resetting an existing service. This is request contains a server-signed confirmation code that must be submitted with the POST call at this endpoint. The confirmation code is mostly to prevent you from accidentally deleting an object.


Resets a service object. The active_until date will be changed to the current date (i.e. deactivated) and all bill and interval data will be deleted. This request requires a signed confirmation code obtained by making a GET request to this endpoint.


  • code - String - A confirmation code which allows you to reset the given service. To acquire a valid code, perform a GET request to this endpoint.


Returns a list of user objects. Right now, it will only return your user object. This probably will only be useful if you forget your user uid.


Not implemented. If you want to create a user, use /users/new. If you want to modify a user, use /users/<uid>/modify.



Returns the requirements for creating a new user. This is most often used by the website to build the user registration form.


Creates a new user. This is most often done via the website rather than the API (if you are using the API, you are probably already a user). Also, instead of requiring an Authorization header, this request requires a CSRF token as a cookie and a field submission.


  • invite - String - An invite code which allows you to register a new user.

  • email - String - The email address associated with the new user.

  • password - String - The password for the new user.

  • password_confirm - String - The password for the new user. Must be identical to password.



Returns a user object. You can only request your own user account for the time being. In future updates, we may start to allow requests of other user objects if they have authorized you to do so.


Not implemented. If you want to create a user, use /users/new. If you want to modify a user, use /users/<uid>/modify.



Returns the requirements for modifying an existing user. This is most often used by the website to build the user settings form.


Modifies a user's details. This is most often used by the website to change a user's contact and notification settings.


  • password - String - Your current password. Required for authorizing changes.

  • email - String - optional - A new email address to associate with the user.

  • new_password - String - optional - A new password to associate with the user. Must be used in conjunction with new_password_confirm.

  • new_password_confirm - String - optional - An identical duplicate of the new_password. Must be used in conjunction with new_password.

  • allow_owner - String - optional - The ID of an admin token associated with another user. If a valid token is found, the user will become a subuser of the user that owns the admin token.



Returns a list of token objects created by the user. See Token Object for the format of each token object.


Not implemented. If you want to create a token, use /tokens/new. If you want to modify a token, use /tokens/<uid>/modify. If you want to expire a token, use /tokens/<uid>/modify.



Returns the options for creating a new token. This is most often used by the website to build the login form.


Creates a new token with the desired options. NOTE: At this time only cookie-based tokens (i.e. browser session ids) have permission to create new tokens. This means that you need to use the website to create api and widget tokens.


  • type - String - The type of token to create. Must be one of the following: "widget", "api", or "admin".

  • expires - ISO8601 - A timestamp that sets the expiration date of the token.



Returns a token object for the requested <uid>, which contains the specific permissions that the token allows.


Not implemented. If you want to create a token, use /tokens/new. If you want to modify a token, use /tokens/<uid>/modify. If you want to invalidate a token, change the expires date to the past using /tokens/<uid>/modify.



Returns the options available to modify on an existing token. This is most often used by the website to build the token settings form.


Modifies an existing token. Use this if you want to change the permissions on the token or expire the token.


  • expires - ISO8601 - optional - A timestamp that sets the expiration date of the token.

  • portal - String - optional - For tokens of type "widget" or "referral", the portal URL will become this value.

  • company_name - String - optional - For tokens of type "widget" or "referral", the company name on the portal will become this value.

  • company_email - String - optional - For tokens of type "widget" or "referral", the company email on the portal will become this value.

  • button - Base64 or String - optional - For tokens of type "widget" or "referral". A base64 encoded string of an image file that will be used in the "button" version of the link to your portal. If "" is submitted, the button will reset to the default UtilityAPI button.

  • logo - Base64 or String - optional - For tokens of type "widget" or "referral". A base64 encoded string of an image file that will be used in place of the UtilityAPI logo at the top of your portal page. If "" is submitted, the logo will reset to the default UtilityAPI logo.

  • after_email - String - optional - For tokens of type "widget" or "referral". An email address that will be notified after usage of your customer portal. A value of "" will reset this to the default.

  • after_redirect - String - optional - For tokens of type "widget" or "referral". A URL to which a customer will be redirected after using your customer portal. A value of "" will reset this to the default.