Meters

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

NOTE: Meter, Bill, and Interval objects have a different format philosophy than Templates, Forms, or Authorizations. Since utility data can be very different across utilities, we try to simplify and contain these differences inside smaller more managable, documented objects called Blocks.

NOTE: Sometimes Meters are not physical meters, but a service that the utility provides to the customer (e.g. an unmetered outdoor lighting service). We still call these meters in this API to keep things simple.

NOTE: Sometimes a Meter is actually a group of physical meters that have been combined into a single service (e.g. a consumption meter and a demand meter are combined into one service). We still call these groupings of meters a single Meter object, since they are billed together. However, we do try to include all the meter numbers in the base Meter Block.

API Endpoints

GET /api/v2/meters List or search your meters
GET /api/v2/meters/123 Get a specific meters
PATCH /api/v2/meters/123 Modify an existing meters
POST /api/v2/meters/historical-collection Collect historical billing and interval data for some meters
POST /api/v2/meters/ongoing-monitoring Start or stop monitoring meters for new bills and intervals

Attributes

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. WARNING: These file formats are not documented and may change, so don't rely on these files existing. They are mainly included for non-API users of our dashboard to have some common non-API download formats. If you want documented formats for bills and intervals, use the /bills and /intervals API endpoints. DEPRECATED: Expect this to be removed in future versions of the API. Use exports_list instead.	`{"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. WARNING: These file formats are not documented and may change, so don't rely on these files existing. They are mainly included for non-API users of our dashboard to have some common non-API download formats. If you want documented formats for bills and intervals, use the /bills and /intervals API endpoints.	`[{'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`

Status Types

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.

Examples

// 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
    }
}