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_code_needed A multi-factor code is needed to complete the authentication. We usually handle this as part of the authorization process, so you should only usually see this if you are polling during an in-progress authorization. If url is null, it's not possible to submit the access code (e.g. the code request timed out), so you can treat this like access_invalid.
  • url - URL or null - A temporary link to embed to submit the multi-factor code.
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
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.
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.
... We may add other types in the future, so be able to handle unknown types 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.