Meters

This is the object representing a utility meter or similar service.


Attribute Format Description Example
uid UID String Unique identifier of the Meter. These uids may appear as integers, but they are not guaranteed to stay that way, so you should treat them as strings. "12345b"
authorization_uid UID String The Authorization under which this Meter belongs. "29re312"
created ISO8601 When the Meter was created. "2016-01-01T12:30:24.653422+00:00"
user_email String Email of the owner the authorization form that was submitted. "sales@acmesolar.com"
user_uid UID String Unique identifier for the owner the authorization form that was submitted. "23456b"
is_archived Boolean Whether the Meter is archived. false
is_activated Boolean Whether a meter has had any data collection performed (historical-collection or ongoing-monitoring) true
notes List(Meter Note) List of notes about the Meter. Will be an empty list if no notes. [{"type": "bills_full", ...}]
status Status Current status of the Meter. "pending"
status_message String Latest verbose message accompanying the latest status. "Found bill 4 of 13! Parsing..."
status_ts ISO8601 Latest update of the current status. "2016-01-01T12:35:24.653422+00:00"
ongoing_monitoring OngoingMonitoring The current ongoing monitoring settings for the Meter. {"frequency": "off", ...}
utility UtilityID Utility for this Meter. "PG&E"
bill_count Integer Number of bills collected. 13
bill_coverage List(ISO8601 tuples) The timespans covered by the bills collected. These are in local timezone of the utility service. [["2015-01-01T00:00:00.000000-08:00", "2015-09-01T00:00:00.000000-07:00"], ...]
bill_sources List(SourceType) The source types for the collected bill data. ["pdf", "website"]
interval_count Integer Number of intervals collected. 35674
interval_coverage List(ISO8601 tuples) The timespans covered by the intervals collected. These are in local timezone of the utility service. [["2015-01-01T00:00:00.000000-08:00", "2015-09-01T00:00:00.000000-07:00"], ...]
interval_sources List(SourceType) The source types for the collected interval data. ["greenbutton_dmd", "website"]
exports Exports

An object containing urls to various non-API downloads for meter, billing, and interval data for this Meter.

{"bills_csv": "https://utilityapi.com/api/v2/files/1111111111", ...}
exports_list Exports List

A List object containing the names and urls to various non-API downloads for meter, billing, and interval data for this Authorization.

[{'name': 'Bills: all bills [csv]','link': "https://utilityapi.com/api/v2/files/1238333328334323.csv"}]
blocks List(MeterBlockType) What MeterBlocks are included with this Meter. ["base", ...]
{block_type} MeterBlock The utility data contents of a MeterBlock that was listed in the blocks list. {"service_identifier": "123456789-0", ...}
is_expanded Boolean Whether the Meter blocks are fully populated. This is true for most utilities, however for some utilities that require special request handling, you need to use the expand_meter_blocks GET parameter to populate all Meter blocks. See the list of utilities that are not expanded by default. true
Type Description
pending We are currently running tasks related to this Meter. This is usually tasks related to collecting Bill and Interval data. We also update the Notes list of the Meter live while our tasks are running, so you don't have to wait for the entire task to complete before you start downloading data, showing the user results, etc.
updated We are done doing all the tasks we need to do for this Meter. See the Notes list for more verbose details about the results of any tasks we performed.
errored We ran into an issue when performing tasks related to this Meter. Like updated, this status indicates we're not currently performing any tasks related to the Meter, but this also indicates that the latest task failed to complete as expected. This generally happens when a utility changes interfaces or returns a new error that isn't currently handled by our system. We monitor these errors and our engineers work to resolve them as soon as they appear.

// Meter with data
{
    "uid": "45678",
    "authorization_uid": "12345",
    "created": "2014-02-17T16:04:34.023534+00:00",
    "user_email": "sales@acmesolar.com",
    "user_uid": "3938",
    "is_archived": false,
    "is_activated": true,
    "is_expanded": true,
    "notes": [
        {
            "type": "access_valid",
            "ts": "2014-06-17T16:06:34.473724+00:00",
            "msg": "Logged in!"
        },
        {
            "type": "meter_full",
            "ts": "2014-06-17T16:06:34.473724+00:00",
            "msg": "Found all meter details."
        },
        {
            "type": "bills_full",
            "ts": "2014-06-17T16:06:34.473724+00:00",
            "msg": "Successfully collected bills."
        },
        {
            "type": "intervals_full",
            "ts": "2014-06-17T16:06:34.473724+00:00",
            "msg": "Successfully collected intervals."
        }
    ],
    "status": "updated",
    "status_message": "Data refreshed",
    "status_ts": "2014-06-17T16:06:34.473724+00:00",
    "ongoing_monitoring": {
        "frequency": "off",
        "prepay": null,
        "next_prepay": null,
        "next_refresh": null,
        "fixed_refresh_day": null
    },
    "utility": "PG&E",
    "bill_count": 25,
    "bill_coverage": [
        ["2012-01-05T07:00:00.000000+00:00", "2014-01-10T07:00:00.000000+00:00"],
    ],
    "bill_sources": ["pdf"],
    "interval_count": 71808,
    "interval_coverage": [
        ["2012-01-05T07:00:00.000000+00:00", "2014-01-10T07:00:00.000000+00:00"],
    ],
    "interval_sources": ["xml"],
    "exports": {
        "bills_csv": "https://utilityapi.com/api/v2/files/1238333328334323.csv",
        "bills_zip": "https://utilityapi.com/api/v2/files/18334323.zip",
        "latest_pdf": "https://utilityapi.com/api/v2/files/latest_pdf?meter=12314",
        "intervals_csv": "https://utilityapi.com/api/v2/files/1238333328334323i.csv",
        "intervals_xml": "https://utilityapi.com/api/v2/files/1238333328334323000.xml"
    },
    "blocks": ["base"],
    "base": {
        "service_identifier": "1234222222-9",
        "service_tariff": "A6X",
        "service_class": "comm-electric",
        "service_address": "222 Broadway St, Suite 100",
        "meter_numbers": ["111.00222.333.002"],
        "billing_contact": "Acme Inc.",
        "billing_address": "222 Broadway St, Suite 100",
        "billing_account": "3456222222-9",
    }
}
// Meter that is currently collecting data
{
    "uid": "45678",
    "authorization_uid": "12345",
    "created": "2014-02-17T16:04:34.023534+00:00",
    "user_email": "sales@acmesolar.com",
    "user_uid": "3938",
    "is_archived": false,
    "is_activated": true,
    "is_expanded": true,
    "notes": [],
    "status": "pending",
    "status_message": "Parsing bill 8 of 14...",
    "status_ts": "2014-06-17T16:06:34.473724+00:00",
    "ongoing_monitoring": {
        "frequency": "off",
        "prepay": null,
        "next_prepay": null,
        "next_refresh": null,
        "fixed_refresh_day": null
    },
    "utility": "PG&E",
    "bill_count": 7,
    "bill_coverage": [
        ["2012-01-05T07:00:00.000000+00:00", "2013-01-10T07:00:00.000000+00:00"]
    ],
    "bill_sources": ["pdf"],
    "interval_count": 71808,
    "interval_coverage": [
        ["2012-01-05T07:00:00.000000+00:00", "2013-01-22T07:00:00.000000+00:00"]
    ],
    "interval_sources": ["greenbutton_dmd"],
    "exports": {
        "bills_csv": "https://utilityapi.com/api/v2/files/1238333328334323.csv",
        "intervals_csv": "https://utilityapi.com/api/v2/files/1238333328334323i.csv"
    },
    "blocks": ["base"],
    "base": {
        "service_identifier": "1234222222-9",
        "service_tariff": "A6X",
        "service_class": "comm-electric",
        "service_address": "222 Broadway St, Suite 100",
        "meter_numbers": [],
        "billing_contact": null,
        "billing_address": null,
        "billing_account": null
    }
}
// Meter that couldn't collect data because the login credentials were changed.
{
    "uid": "45678",
    "authorization_uid": "12345",
    "created": "2014-02-17T16:04:34.023534+00:00",
    "user_email": "sales@acmesolar.com",
    "user_uid": "3938",
    "is_archived": false,
    "is_activated": true,
    "is_expanded": true,
    "notes": [
        {
            "type": "access_invalid",
            "msg": "Unable to login to collect data.",
            "ts": "2016-01-01T12:31:42.347321+00:00"
        }
    ],
    "status": "errored",
    "status_message": "Login issue, see notes.",
    "status_ts": "2016-01-01T12:31:42.347321+00:00",
    "ongoing_monitoring": {
        "frequency": "off",
        "prepay": null,
        "next_prepay": null,
        "next_refresh": null,
        "fixed_refresh_day": null
    },
    "utility": "PG&E",
    "bill_count": 0,
    "bill_coverage": [],
    "bill_sources": [],
    "interval_count": 0,
    "interval_coverage": [],
    "interval_sources": [],
    "exports": {},
    "blocks": ["base"],
    "base": {
        "service_identifier": null,
        "service_tariff": null,
        "service_class": null,
        "service_address": null,
        "meter_numbers": [],
        "billing_contact": null,
        "billing_address": null,
        "billing_account": null
    }
}