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).
// 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",
}
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.

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.