Meter Notes

You will see these Meter notes in the Meter['notes'] list.

Since collecting data can be fairly complex, with different steps happening a different times, we have several states we like to keep track of to make the user experience better. For example, when go to collect bill and interval data for a meter, we sometimes find that interval data isn't available from the utility. Notes give us a way to inform you that we confirmed there was no interval data available so you're not left wondering if there will be interval data for a meter.

Attribute	Format	Description	Example
`type`	Note Type	The type of note. See list below for list of types.	`"intervals_empty"`
`msg`	String	A human readable description of the note. It may be tweaked often, so don't rely on it always staying the same for a given type.	`"Found no intervals for this meter."`
`ts`	ISO8601	The timestamp of the note.	`"2016-01-01T12:30:24.653422+00:00"`
…		Extra attributes based on `type` (see below).

Examples

// Example bills_errored note
{
    "type": "bills_errored",
    "msg": "All the bills listed returned errors from the utility.",
    "ts": "2019-01-01T12:32:42.347321+00:00"
}

// Example waiting note
{
    "type": "waiting",
    "msg": "Waiting for other data collections on this account to finish...",
    "ts": "2019-01-01T12:35:42.347321+00:00",
    "eta ": "2019-01-01T12:38:42.347321+00:00"
}

// Example strange note
{
    "type": "bills_strange",
    "bill_note_type": "audit_failed_on_line_items",
    "bill_statement_date": "2016-01-31:17:00:00.000000+00:00",
    "bill_uid": "123456",
    "msg": "One of this meter's bills has line items that don't add up. Please double check to make sure the data is correct.",
    "ts": "2018-04-24T11:04:21.481999+00:00",
}

Meter Note Types

Type	Description	Additional Attributes
`access_valid`	In the latest collection, access credentials (login or token) worked.
`access_invalid`	In the latest collection, access credentials did not work. The customer needs to update the authorization to fix the access fields that are invalid.
`access_locked`	Access to the customer's account has been locked. This usually happens when the customer tries invalid login credentials too many times.
`access_expired`	Access to the customer's account has expired either due to the scope of the Authorization or one party requested it (utility, customer, or user).
`access_unsupported`	We found we do not support the full access method for the user. This usually comes up when we encounter a multi-factor process that we do not yet support. For supported multi-factor methods, you'll see an `access_code_needed` or `interaction_needed` note.
`access_code_needed`	We ran into a multi-factor access process outside of the normal authorization process, so we need the utility customer to re-authorize access again. This typically happens if you're refreshing or monitoring some meters, and the user's session we had been given access to during authorization expired or became stale. To fix this, all you need to do is send an authorization update request to the utility customer and we'll get a new session.
`incomplete_registration`	The account has been created by the utility but there are some more steps the account holder must complete before we can access data. For example, many utilities require users to accept the terms of service the first time they log in.
`interaction_needed`	We need you or the customer to provide some additional information for the authorization to proceed. This usually happens when we need to ask for a multi-factor access code, to solve a captcha, or to answer a question about the authorization (e.g. "Is this login for the commercial portal?"). Visit the provided `url` to perform this interaction. NOTE: This note is usually for an "in-the-moment" interaction, and you'll only see it while the `url` is still valid. We try to include an estimated `expires` time, but if the url expires before then (e.g. we saw things timeout on the utility side), this note may disappear early. Also, the opposite can be true, where we are able to extend the validity period past the estimated expiration (if you're polling you'll see the expires time for this note switch to a date further in the future).	`url` - URL - A link to the temporary information request. `expires` - ISO8601 or `null` - Estimated expiration time, if any.
`revoked`	The Authorization for this Meter has been revoked, so all of this Meter data has been deleted.
`meters_full`	We successfully collected all the Meter details we could find.
`meters_partial`	We were able to collect some Meter details, but some sources returned errors from the utility, so they were skipped.
`meter_not_found`	In the latest collection, the meter was no longer accessible within its authorization.
`meter_stale`	We haven't seen this meter in recent collections so it's unlikely that new data is available. Service for this meter may have stopped but we haven't seen a note to that effect from the utility so we aren't sure.	`last_seen` - ISO8601 - The last time we saw this meter in a collection or authorization job
`meter_stopped`	We found a note from the utility that this meter was stopped so don't expect future data collections to turn up any new bill or interval data.	`source` - Source - The document that contains the message from the utility indicating that service has stopped for this meter
`meters_strange`	Some information about this meter did not pass our audits. The specified field should be considered suspect.	`field` - String - The field that should be considered suspect, in the format <Meter Block>.<field>
`meter_cca`	This meter is a CCA service that was created before we added the suppliers block and so will no longer be updated. The note points to the meter that will have suppliers blocks for this CCA service.	`parent_meter_uid` - UID String - The UID of the meter with suppliers blocks that replace this meter's bills
`bills_full`	We successfully collected all the bills we found.
`bills_errored`	We weren't able to collect any bills because the utility returned errors for all bills.
`bills_empty`	We confirmed there aren't any bills available for this Meter.
`bills_partial`	We were able to collect some bill data, but some bills returned errors from the utility, so they were skipped.
`bills_strange`	Some of the bills had unexpected information and didn't pass our audits. The listed fields should be considered suspect.	`bill_note_type` - BillNoteType - The type of note on the affected bill `bill_statement_date` - ISO8601 - The statement date of the relevant bill `bill_uid` - UID - The UID of the bill with the note
`intervals_full`	We successfully collected all the intervals we found.
`intervals_errored`	We weren't able to collect any intervals because the utility returned errors for all intervals.
`intervals_empty`	We confirmed there aren't any intervals available for this Meter.
`intervals_partial`	We were able to collect some bill data, but some intervals returned errors from the utility, so they were skipped.
`intervals_mixed`	This set of intervals has multiple durations, for example some 15 minute intervals and some hourly intervals. We will only show intervals of the majority duration on the API unless the mixed data is specifically requested.	`ranges` - List(MixedIntervalRange) - A list of ranges of interval data with the same duration
`utility_down`	The utility appears to be down for maintenance. Data collection will be attempted later.
`account_down`	The utility reported a problem with this account that prevented us from collecting some or all of the data. This can be temporary but if it occurs repeatedly then the account holder may have to login and manually fix the problem.
`internal_error`	Something unexpected went wrong when trying to collect data, and we are working on a fix.
`retrying`	We encountered an error, and will be automatically retrying in a moment.	`eta` - ISO8601 - When the retry is scheduled.
`waiting`	The task is waiting for other jobs to complete (usually to prevent getting locked out), and will start in a moment.	`eta` - ISO8601 - When the task will check again to see if it should run.
`wait_to_login`	Access to the customer's account has been temporarily limited or blocked by the utility. The utility may restore access at any time so you may want to try historical collections again after waiting a while.
`pending_manual`	UtilityAPI has to manually collect the data from this utility for you. We constantly monitor for such cases, and no further action is needed on your part.
Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

MixedIntervalRange

This is an object representing the duration of a particular range of intervals.

Attribute	Type	Description
`start`	ISO8601	The start date of the range.
`end`	ISO8601	The end date of the range.
`duration`	Integer	The duration of the intervals in this range in seconds.