1. Documentation
  2. Green Button
  3. XML Format

Green Button XML Format

Green Button specifies a full XML schema for representing a utility customer's account, bill, and usage data. The schema is composed of specific object types that represent certain parts of a customer's data. These objects can be combined into an Atom Feed or downloaded individually.

At UtilityAPI, you can download Green Button XML formatted versions for any authorization on your dashboard or via our Green Button API.

Here are the official Green Button XML Schemas:

For the Green Button XML exports on your dashboard and batch endpoints on our Green Button API, we merge all of the relevant Green Button objects into an Atom Feed . This lets you read through all of the data objects as a list of entries. Each of these <entry> items can have links (<link> tags) that you can use to connect objects to each other.

Here's an example of what a typical feed of greenbutton xml objects looks like: 

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>3afa16f7-15e5-459f-b70d-429e3b62466f</id>
  <link rel="self"  href="https://utilityapi.com/DataCustodian/espi/1_1/resource/Batch/Subscription/1a1a1a/UsagePoint/2b2b2b"></link>
  <title>Batch Feed</title>
  <updated>2018-01-01T00:00:00+00:00</updated>
  <entry xmlns="http://www.w3.org/2005/Atom">
    <id>2fac0a41-8e44-4ed5-9d0f-78c0e2e4af9a</id>
    <link rel="self" href="https://utilityapi.com/DataCustodian/espi/1_1/resource/Subscription/1a1a1a/UsagePoint/2b2b2b/MeterReading/3c3c3c/IntervalBlock/01"/>
    <link rel="up" href="https://utilityapi.com/DataCustodian/espi/1_1/resource/Subscription/1a1a1a/UsagePoint/2b2b2b/MeterReading/3c3c3c/IntervalBlock"/>
    <published>2018-01-01T00:00:00+00:00</published>
    <updated>2018-01-01T00:00:00+00:00</updated>
    <title/>
    <content>
      <IntervalBlock xmlns="http://naesb.org/espi" xmlns:espi="http://naesb.org/espi">
        ...
      </IntervalBlock>
    </content>
  </entry>
  <entry xmlns="http://www.w3.org/2005/Atom">
    <id>611104fd-b3ef-4f99-be65-6dee50b94fa8</id>
    <link rel="self" href="https://utilityapi.com/DataCustodian/espi/1_1/resource/Subscription/1a1a1a/UsagePoint/2b2b2b/MeterReading/4d4d4d/IntervalBlock/01"/>
    <link rel="up" href="https://utilityapi.com/DataCustodian/espi/1_1/resource/Subscription/1a1a1a/UsagePoint/2b2b2b/MeterReading/4d4d4d/IntervalBlock"/>
    <published>2018-01-01T00:00:00+00:00</published>
    <updated>2018-01-01T00:00:00+00:00</updated>
    <title/>
    <content>
      <IntervalBlock xmlns="http://naesb.org/espi" xmlns:espi="http://naesb.org/espi">
        ...
      </IntervalBlock>
    </content>
  </entry>
  ...
</feed>

In <entry> items, you will see some <link> tags that contain urls to other endpoints on the API.

  • <link rel="self"... - Permalink for the entry.
  • <link rel="up"... - Parent for the entry.
  • <link rel="related"... - These are resources related to the entry (see below for where you will see these).

You will see related links to other resources for the following entries:

Entry Object Types

Below are the various objects you may see in our greenbutton xml feeds.

  • Description: Information about third party registration status and base urls for the Green Button API.
  • Fields:
    • dataCustodianApplicationStatus - integer - Status of the third party at the utility.
      • 1 - Under Review
      • 2 - In Production
      • 3 - On Hold
      • 4 - Revoked
    • dataCustodianResourceEndpoint - url - The base url for the REST API.
    • authorizationServerAuthorizationEndpoint - url - The OAuth authorize url (see OAuth Step 1).
    • authorizationServerTokenEndpoint - url - The OAuth token url (see OAuth Step 4).
    • redirect_uri - url - Third party OAuth redirect url (see OAuth Step 3).
    • thirdPartyNotifyUri - url - Third party notification endpoint (e.g. where to POST new data notifications).
    • client_id - string - Client identifier used for API authentication.
    • client_secret - string - Client secret used for API authentication.
    • registration_access_token - string - Access token for requesting GET /ApplicationInformation/{app_uid}.
    • thirdPartyApplicationDescription* - string - Third party submitted description.
    • thirdPartyApplicationStatus* - integer - Third party app status.
      • 1 - Development
      • 2 - ReviewTest
      • 3 - Production
      • 4 - Retired
    • thirdPartyApplicationType* - integer - The type of third party app.
      • 1 - Web
      • 2 - Desktop
      • 3 - Mobile
      • 4 - Device
    • thirdPartyApplicationUse* - integer - How the third party app is used.
      • 1 - EnergyManagement
      • 2 - Comparisons
      • 3 - Government
      • 4 - Academic
      • 5 - LawEnforcement
    • thirdPartyPhone* - string - Third party phone number.
    • authorizationServerUri* - url - The OAuth base url (e.g. where /authorize and /token live).
    • authorizationServerRegistrationEndpoint* - url - Where third parties can register.
    • dataCustodianBulkRequestURI - url - API endpoint for GET /Bulk/{bulk_uid}.
    • thirdPartyScopeSelectionScreenURI - url - Where to redirect customer when they select a third party on utility website.
    • thirdPartyUserPortalScreenURI* - url - Link to third party data sharing portal.
    • logo_uri* - url - Third party logo url.
    • client_name - string - Third party name.
    • client_uri* - url - Third party generic url.
    • tos_uri* - url - Third party terms of service url.
    • policy_uri* - url - Third party privacy policy url.
    • software_id - string - Third party app software name.
    • software_version - string - Third party app software version number.
    • client_id_issued_at - timestamp - When client_id was issued.
    • client_secret_expires_at - timestamp - When client_secret will expire.
    • contacts*† - string - Third party contact emails.
    • token_endpoint_auth_method - string - How to authenicate on /token endpoint (will be "client_secret_basic").
    • scope† - string - The default scope string for authorizations.
    • grant_types† - string - Allowed OAuth 2.0 grant types.
      • client_credentials
      • authorization_code
      • refresh_token
    • response_types - string - Allowed OAuth 2.0 response types.
      • code
    • registration_client_uri - url - Where customers can register for third party.
    • dataCustodianId - string - Name of the utility.
    • dataCustodianScopeSelectionScreenURI - url - Where utility customers can manage and add third party authorizations.
  • Where will you see it?
  • Description: Information about a specific customer authorization to share data with a third party.
  • Fields:
    • authorizedPeriod* - duration - How long the authorization is valid for ("0" means never expires).
    • publishedPeriod* - duration - The overall date range of available data.
    • status - integer - The overall status of the authorization.
      • 0 - Revoked
      • 1 - Active
      • 2 - Denied
    • expires_at - timestamp - When the authorization will expire.
    • grant_type* - enum - OAuth 2.0 grant type for the authorization.
      • client_credentials
      • authorization_code
      • refresh_token
    • scope - string - The authorization scope (see Green Button Authorization Scope).
    • token_type - enum - OAuth 2.0 token type to use when authenticating.
      • "Bearer"
    • error* - enum - OAuth 2.0 error type, if any.
      • invalid_request
      • invalid_client
      • invalid_grant
      • unauthorized_client
      • unsupported_grant_type
      • invalid_redirect_uri
      • invalid_client_metadata
      • invalid_client_id
      • access_denied
      • unsupported_response_type
      • server_error
      • temporarily_unavailable
    • error_description* - string - Description of OAuth 2.0 error, if any.
    • error_uri* - url - Link to more information on OAuth 2.0 error, if any.
    • resourceURI - url - Url for GET /Batch/Subscription/{auth_uid}.
    • authorizationURI - url - Url for GET /Authorization/{auth_uid}.
  • Where will you see it?
  • Description: This object is what is sent to the third party notification url.
  • Fields:
    • resources*† - url - A link to a new data or bulk resource on the API. You can receive multiple resources entries.
  • Where will you see it?
    • In your notify payloads.
  • Description: A summary of the electric power quality for a specific time period
  • Fields:
    • summaryInterval - duration - The time period this summary covers.
    • flickerPlt* - integer - The long term rapid voltage change.
    • flickerPst* - integer - The likelyhood that voltage fluctuations would result in flicker.
    • harmonicVoltage* - integer - The harmonic voltage for the period.
    • longInterruptions* - integer - How many long interruption events occurred.
    • mainsVoltage* - integer - What the mains voltage was.
    • measurementProtocol* - integer - What what standard measurement protocol was.
    • powerFrequency* - integer - A reading of the power frequency.
    • rapidVoltageChanges* - integer - How many rapid voltage changes occurred.
    • shortInterruptions* - integer - How many short interruption events occurred.
    • supplyVoltageDips* - integer - How many supply voltage dips occurred.
    • supplyVoltageVariations* - integer - How many supply voltage variations occurred.
    • tempOvervoltage* - integer - How many temporary over-voltage events occurred.
  • Where will you see it?
  • Description: Contains a set of interval reading values for a specific time period.
  • Fields:
    • interval - duration - The start and duration of this interval reading set.
    • IntervalReading† - object - One of the actual interval readings.
      • timePeriod* - duration - The start and duration of the interval.
      • value* - integer - The reading value of the interval.
      • cost* - integer - How much this interval cost, in hundred-thousandths of the currency.
      • ReadingQuality*† - enum - The quality of the interval.
        • 0 - valid
        • 7 - manually edited
        • 8 - estimated using reference day
        • 9 - estimated using linear interpolation
        • 10 - questionable
        • 11 - derived
        • 12 - projected (forecast)
        • 13 - mixed
        • 14 - raw
        • 15 - normalized for weather
        • 16 - other
        • 17 - validated
        • 18 - verified
        • 19 - revenue-quality
      • consumptionTier* - integer - The code for the consumption tier for the interval.
      • tou* - integer - The code for the time-of-use period for the interval.
      • cpp* - integer - The critical peak period bucket.
  • Where will you see it?
  • Description: The characteristics associated with a set of meter readings.
  • Fields:
    • accumulationBehaviour* - enum - How the values in the readings were accumulated.
      • 0 - none
      • 1 - bulkQuantity
      • 2 - continuousCumulative
      • 3 - cumulative
      • 4 - deltaData
      • 6 - indicating
      • 9 - summation
      • 10 - timeDelay
      • 12 - instantaneous
      • 13 - latchingQuantity
      • 14 - boundedQuantity
    • commodity* - enum - The type of commodity being read.
      • 0 - none
      • 1 - electricity SecondaryMetered
      • 2 - electricity PrimaryMetered
      • 3 - communication
      • 4 - air
      • 5 - insulativeGas
      • 6 - insulativeOil
      • 7 - naturalGas
      • 8 - propane
      • 9 - potableWater
      • 10 - steam
      • 11 - wasteWater
      • 12 - heatingFluid
      • 13 - coolingFluid
      • 14 - nonpotableWater
      • 15 - nox
      • 16 - so2
      • 17 - ch4
      • 18 - co2
      • 19 - carbon
      • 20 - hch
      • 21 - pfc
      • 22 - sf6
      • 23 - tvLicence
      • 24 - internet
      • 25 - refuse
      • 26 - electricity TransmissionMetered
    • consumptionTier* - integer - The default consumption tier for the readings.
    • currency* - enum - The currency of cost values in the readings.
      • 840 - USD
      • 978 - EUR
      • 36 - AUD
      • 124 - CAD
      • 756 - CHF
      • 156 - CNY
      • 208 - DKK
      • 826 - GBP
      • 392 - JPY
      • 578 - NOK
      • 643 - RUB
      • 752 - SEK
      • 356 - INR
      • 0 - other
    • dataQualifier* - enum - The salient type for the readings.
      • 0 - none
      • 2 - average
      • 4 - excess
      • 5 - highThreshold
      • 7 - lowThreshold
      • 8 - maximum
      • 9 - minimum
      • 11 - nominal
      • 12 - normal
      • 16 - secondMaximum
      • 17 - secondMinimum
      • 23 - thirdMaximum
      • 24 - fourthMaximum
      • 25 - fifthMaximum
      • 26 - sum
    • defaultQuality* - enum - The default quality of the readings.
      • 0 - valid
      • 7 - manually edited
      • 8 - estimated using reference day
      • 9 - estimated using linear interpolation
      • 10 - questionable
      • 11 - derived
      • 12 - projected (forecast)
      • 13 - mixed
      • 14 - raw
      • 15 - normalized for weather
      • 16 - other
      • 17 - validated
      • 18 - verified
      • 19 - revenue-quality
    • flowDirection* - enum - The direction of flow for values in the readings.
      • 0 - none
      • 1 - forward
      • 2 - lagging
      • 3 - leading
      • 4 - net
      • 5 - q1plusQ2
      • 7 - q1plusQ3
      • 8 - q1plusQ4
      • 9 - q1minusQ4
      • 10 - q2plusQ3
      • 11 - q2plusQ4
      • 12 - q2minusQ3
      • 13 - q3plusQ4
      • 14 - q3minusQ2
      • 15 - quadrant1
      • 16 - quadrant2
      • 17 - quadrant3
      • 18 - quadrant4
      • 19 - reverse
      • 20 - total
      • 21 - totalByPhase
    • intervalLength* - integer - The default interval length in seconds.
    • kind* - enum - What the value represents in the readings.
      • 0 - none
      • 2 - apparentPowerFactor
      • 3 - currency
      • 4 - current
      • 5 - currentAngle
      • 6 - currentImbalance
      • 7 - date
      • 8 - demand
      • 9 - distance
      • 10 - distortionVoltAmperes
      • 11 - energization
      • 12 - energy
      • 13 - energizationLoadSide
      • 14 - fan
      • 15 - frequency
      • 16 - Funds
      • 17 - ieee1366ASAI
      • 18 - ieee1366ASIDI
      • 19 - ieee1366ASIFI
      • 20 - ieee1366CAIDI
      • 21 - ieee1366CAIFI
      • 22 - ieee1366CEMIn
      • 23 - ieee1366CEMSMIn
      • 24 - ieee1366CTAIDI
      • 25 - ieee1366MAIFI
      • 26 - ieee1366MAIFIe
      • 27 - ieee1366SAIDI
      • 28 - ieee1366SAIFI
      • 31 - lineLosses
      • 32 - losses
      • 33 - negativeSequence
      • 34 - phasorPowerFactor
      • 35 - phasorReactivePower
      • 36 - positiveSequence
      • 37 - power
      • 38 - powerFactor
      • 40 - quantityPower
      • 41 - sag
      • 42 - swell
      • 43 - switchPosition
      • 44 - tapPosition
      • 45 - tariffRate
      • 46 - temperature
      • 47 - totalHarmonicDistortion
      • 48 - transformerLosses
      • 49 - unipedeVoltageDip10to15
      • 50 - unipedeVoltageDip15to30
      • 51 - unipedeVoltageDip30to60
      • 52 - unipedeVoltageDip60to90
      • 53 - unipedeVoltageDip90to100
      • 54 - voltage
      • 55 - voltageAngle
      • 56 - voltageExcursion
      • 57 - voltageImbalance
      • 58 - volume
      • 59 - zeroFlowDuration
      • 60 - zeroSequence
      • 64 - distortionPowerFactor
      • 81 - frequencyExcursion
      • 90 - applicationContext
      • 91 - apTitle
      • 92 - assetNumber
      • 93 - bandwidth
      • 94 - batteryVoltage
      • 95 - broadcastAddress
      • 96 - deviceAddressType1
      • 97 - deviceAddressType2
      • 98 - deviceAddressType3
      • 99 - deviceAddressType4
      • 100 - deviceClass
      • 101 - electronicSerialNumber
      • 102 - endDeviceID
      • 103 - groupAddressType1
      • 104 - groupAddressType2
      • 105 - groupAddressType3
      • 106 - groupAddressType4
      • 107 - ipAddress
      • 108 - macAddress
      • 109 - mfgAssignedConfigurationID
      • 110 - mfgAssignedPhysicalSerialNumber
      • 111 - mfgAssignedProductNumber
      • 112 - mfgAssignedUniqueCommunicationAddress
      • 113 - multiCastAddress
      • 114 - oneWayAddress
      • 115 - signalStrength
      • 116 - twoWayAddress
      • 117 - signaltoNoiseRatio
      • 118 - alarm
      • 119 - batteryCarryover
      • 120 - dataOverflowAlarm
      • 121 - demandLimit
      • 122 - demandReset
      • 123 - diagnostic
      • 124 - emergencyLimit
      • 125 - encoderTamper
      • 126 - ieee1366MomentaryInterruption
      • 127 - ieee1366MomentaryInterruptionEvent
      • 128 - ieee1366SustainedInterruption
      • 129 - interruptionBehaviour
      • 130 - inversionTamper
      • 131 - loadInterrupt
      • 132 - loadShed
      • 133 - maintenance
      • 134 - physicalTamper
      • 135 - powerLossTamper
      • 136 - powerOutage
      • 137 - powerQuality
      • 138 - powerRestoration
      • 139 - programmed
      • 140 - pushbutton
      • 141 - relayActivation
      • 142 - relayCycle
      • 143 - removalTamper
      • 144 - reprogrammingTamper
      • 145 - reverseRotationTamper
      • 146 - switchArmed
      • 147 - switchDisabled
      • 148 - tamper
      • 149 - watchdogTimeout
      • 150 - billLastPeriod
      • 151 - billToDate
      • 152 - billCarryover
      • 153 - connectionFee
      • 154 - audibleVolume
      • 155 - volumetricFlow
    • PhaseCodeKind* - enum - The kind of phase code associated with the readings.
      • 225 - ABCN
      • 224 - ABC
      • 193 - ABN
      • 41 - ACN
      • 97 - BCN
      • 132 - AB
      • 96 - AC
      • 66 - BC
      • 129 - AN
      • 65 - BN
      • 33 - CN
      • 128 - A
      • 64 - B
      • 32 - C
      • 16 - N
      • 272 - S2N
      • 784 - S12N
      • 528 - S1N
      • 256 - S2
      • 768 - S12
      • 769 - S12N
      • 0 - none
      • 136 - AtoAv
      • 72 - BAv
      • 40 - CAv
      • 17 - NG
      • 512 - S1
    • powerOfTenMultiplier* - enum - The power to multiply the value by to get the unit of measure.
      • -12 - Pico
      • -9 - Nano
      • -6 - Micro
      • -3 - Milli
      • -2 - Centi
      • -1 - Deci
      • 0 - None
      • 1 - Deca
      • 2 - Hecto
      • 3 - Kilo
      • 6 - Mega
      • 9 - Giga
      • 12 - Tera
    • timeAttribute* - enum - The classification of the time period of the readings.
      • 0 - none
      • 8 - billingPeriod
      • 11 - daily
      • 13 - monthly
      • 22 - seasonal
      • 24 - weekly
      • 32 - specifiedPeriod
    • tou* - integer - The code for the default time-of-use period for the readings.
    • uom* - enum - The unit of measure for the readings.
      • 61 - VA
      • 38 - W
      • 63 - VAr
      • 71 - VAh
      • 72 - Wh
      • 73 - VArh
      • 29 - V
      • 30 - ohm
      • 5 - A
      • 25 - F
      • 28 - H
      • 23 - degC
      • 27 - sec
      • 159 - min
      • 160 - h
      • 9 - deg
      • 10 - rad
      • 31 - J
      • 32 - n
      • 53 - siemens
      • 0 - none
      • 33 - Hz
      • 3 - g
      • 39 - pa
      • 0 - none
      • 2 - m
      • 41 - m2
      • 42 - m3
      • 69 - A2
      • 105 - A2h
      • 70 - A2s
      • 106 - Ah
      • 152 - APerA
      • 103 - APerM
      • 68 - As
      • 79 - b
      • 113 - bm
      • 22 - bq
      • 132 - btu
      • 133 - btuPerH
      • 8 - cd
      • 76 - char
      • 75 - HzPerSec
      • 114 - code
      • 65 - cosTheta
      • 111 - count
      • 119 - ft3
      • 120 - ft3compensated
      • 123 - ft3compensatedPerH
      • 78 - gM2
      • 144 - gPerG
      • 21 - gy
      • 150 - HzPerHz
      • 77 - charPerSec
      • 130 - imperialGal
      • 131 - imperialGalPerH
      • 51 - jPerK
      • 165 - jPerKg
      • 6 - K
      • 158 - kat
      • 47 - kgM
      • 48 - kgPerM3
      • 134 - litre
      • 157 - litreCompensated
      • 138 - litreCompensatedPerH
      • 137 - litrePerH
      • 143 - litrePerLitre
      • 82 - litrePerSec
      • 156 - litreUncompensated
      • 139 - litreUncompensatedPerH
      • 35 - lm
      • 34 - lx
      • 49 - m2PerSec
      • 167 - m3compensated
      • 126 - m3compensatedPerH
      • 125 - m3PerH
      • 45 - m3PerSec
      • 166 - m3uncompensated
      • 127 - m3uncompensatedPerH
      • 118 - meCode
      • 7 - mol
      • 147 - molPerKg
      • 145 - molPerM3
      • 146 - molPerMol
      • 80 - money
      • 148 - mPerM
      • 46 - mPerM3
      • 43 - mPerSec
      • 44 - mPerSec2
      • 102 - ohmM
      • 155 - paA
      • 140 - paG
      • 141 - psiA
      • 142 - psiG
      • 100 - q
      • 161 - q45
      • 163 - q45h
      • 162 - q60
      • 164 - q60h
      • 101 - qh
      • 54 - radPerSec
      • 154 - rev
      • 4 - revPerSec
      • 149 - secPerSec
      • 11 - sr
      • 109 - status
      • 24 - sv
      • 37 - t
      • 169 - therm
      • 108 - timeStamp
      • 128 - usGal
      • 129 - usGalPerH
      • 67 - V2
      • 104 - V2h
      • 117 - VAhPerRev
      • 116 - VArhPerRev
      • 74 - VPerHz
      • 151 - VPerV
      • 66 - Vs
      • 36 - wb
      • 107 - WhPerM3
      • 115 - WhPerRev
      • 50 - wPerMK
      • 81 - WPerSec
      • 153 - WPerVA
      • 168 - WPerW
    • tou* - integer - The default critical peak period bucket for the readings.
    • interharmonic* - fraction - A basis of harmonic or interharmonic indication for the readings.
    • measuringPeriod* - enum - A time attribute inherent to the values in the readings.
      • 0 - none
      • 1 - tenMinute
      • 2 - fifteenMinute
      • 3 - oneMinute
      • 4 - twentyfourHour
      • 5 - thirtyMinute
      • 6 - fiveMinute
      • 7 - sixtyMinute
      • 10 - twoMinute
      • 14 - threeMinute
      • 15 - present
      • 16 - previous
      • 31 - twentyMinute
      • 50 - fixedBlock60Min
      • 51 - fixedBlock30Min
      • 52 - fixedBlock20Min
      • 53 - fixedBlock15Min
      • 54 - fixedBlock10Min
      • 55 - fixedBlock5Min
      • 56 - fixedBlock1Min
      • 57 - rollingBlock60MinIntvl30MinSubIntvl
      • 58 - rollingBlock60MinIntvl20MinSubIntvl
      • 59 - rollingBlock60MinIntvl15MinSubIntvl
      • 60 - rollingBlock60MinIntvl12MinSubIntvl
      • 61 - rollingBlock60MinIntvl10MinSubIntvl
      • 62 - rollingBlock60MinIntvl6MinSubIntvl
      • 63 - rollingBlock60MinIntvl5MinSubIntvl
      • 64 - rollingBlock60MinIntvl4MinSubIntvl
      • 65 - rollingBlock30MinIntvl15MinSubIntvl
      • 66 - rollingBlock30MinIntvl10MinSubIntvl
      • 67 - rollingBlock30MinIntvl6MinSubIntvl
      • 68 - rollingBlock30MinIntvl5MinSubIntvl
      • 69 - rollingBlock30MinIntvl3MinSubIntvl
      • 70 - rollingBlock30MinIntvl2MinSubIntvl
      • 71 - rollingBlock15MinIntvl5MinSubIntvl
      • 72 - rollingBlock15MinIntvl3MinSubIntvl
      • 73 - rollingBlock15MinIntvl1MinSubIntvl
      • 74 - rollingBlock10MinIntvl5MinSubIntvl
      • 75 - rollingBlock10MinIntvl2MinSubIntvl
      • 76 - rollingBlock10MinIntvl1MinSubIntvl
      • 77 - rollingBlock5MinIntvl1MinSubIntvl
    • argument* - fraction - An argument used to convert the value to the unit of measure.
  • Where will you see it?
  • Description: Information about the status of our Green Button API.
  • Fields:
    • currentStatus - enum - The current status of the API.
      • 0 - Unavailable
      • 1 - Normal
  • Where will you see it?
  • Description: This represents a individual point of measured usage (e.g. a meter).
  • Fields:
    • roleFlags* - hex - Bits noting the roles assigned to this usage point.
    • ServiceCategory* - object - The type of service that this usage point is used for.
      • kind - enum - The type of service.
        • 0 - electricity
        • 1 - gas
        • 2 - water
        • 3 - time
        • 4 - heat
        • 5 - refuse
        • 6 - sewerage
        • 7 - rates
        • 8 - tvLicence
        • 9 - internet
    • status* - integer - The current status of the usage point (0 = off, 1 = on).
    • ServiceDeliveryPoint* - object - Details about the service that this usage point is used for.
      • name* - string - The name of the service.
      • tariffProfile* - string - The tariff rate schedule for the service.
      • customerAgreement* - string - The service agreement id or contract.
      • tariffRiderRefs* - object - A list of tariff riders that are applied to this service.
        • tariffRiderRef*† - object - A specific tariff rider.
          • riderType - string - The name or type of tariff rider.
          • enrollmentStatus - enum - The current status of the rider.
            • unenrolled
            • enrolled
            • enrolledPending
          • effectiveDate - timestamp - When the rider became effective.
    • amiBillingReady* - enum - The readiness status for billing.
      • amiCapable
      • amiDisabled
      • billingApproved
      • enabled
      • nonAmi
      • nonMetered
      • operable
    • checkBilling* - boolean - Whether there may currently be a problem with billing.
    • connectionState* - enum - The status of connection to the network.
      • connected
      • logicallyDisconnected
      • physicallyDisconnected
    • estimatedLoad* - measurement - The load estimate for this usage point.
    • grounded* - boolean - Whether this usage point is grounded.
    • isSdp* - boolean - Whether a service delivery point where the service changes hands.
    • isVirtual* - boolean - Whether this represents a virtual, not physical, usage point.
    • minimalUsageExpected* - boolean - Whether minimal usage is expected from this usage point.
    • nominalServiceVoltage* - measurement - The nominal service voltage for this usage point.
    • outageRegion* - string - The outage region(s) that this usage point is in.
    • phaseCode* - enum - The kind of phase code associated with this usage point.
      • 225 - ABCN
      • 224 - ABC
      • 193 - ABN
      • 41 - ACN
      • 97 - BCN
      • 132 - AB
      • 96 - AC
      • 66 - BC
      • 129 - AN
      • 65 - BN
      • 33 - CN
      • 128 - A
      • 64 - B
      • 32 - C
      • 16 - N
      • 272 - S2N
      • 784 - S12N
      • 528 - S1N
      • 256 - S2
      • 768 - S12
      • 769 - S12N
      • 0 - none
      • 136 - AtoAv
      • 72 - BAv
      • 40 - CAv
      • 17 - NG
      • 512 - S1
    • ratedCurrent* - measurement - The current flow that this usage point is configured to deliver.
    • ratedPower* - measurement - The power that this usage point is configured to deliver.
    • readCycle* - string - The schedule on which the usage point is read.
    • readRoute* - string - Route ID used for reading the usage point.
    • serviceDeliveryRemark* - string - Notes about the service delivery.
    • servicePriority* - string - The level of priority for this service.
    • pnodeRefs* - object - What pnodes this usage point is assigned to.
      • pnodeRef† - object - A specific pnode.
        • apnodeType - enum - The type of pnode.
          • AG - Aggregated Generation
          • CPZ - Custom Price Zone
          • DPZ - Default Price Zone
          • LAP - Load Aggregation Point
          • TH - Trading Hub
          • SYS - System Zone
          • CA - Control Area
          • DCA - Designated Congestion Area
          • GA - generic aggregation
          • GH - generic hub
          • EHV - 500 kV - Extra High Voltage aggregate price nodes
          • ZN - Zone
          • INT - Interface
          • BUS - Bus
        • ref - string - The reference name of the pnode.
        • startEffectiveDate* - timestamp - When the pnode assignment became effective.
        • endEffectiveDate* - timestamp - When the pnode assignment ended.
    • aggregateNodeRefs* - object - What aggregation nodes this usage point is assigned to.
      • aggregateNodeRef† - object - A specific aggregation node.
        • anodeType - enum - The type of aggregation node.
          • SYS - System Zone/Region
          • RUC - RUC Zone
          • LFZ - Load Forecast Zone
          • REG - Market Energy/Ancillary Service Region
          • AGR - Aggregate Generation Resource
          • POD - Point of Delivery
          • ALR - Aggregate Load Resource
          • LTAC - Load TransmissionAccessCharge (TAC) Group
          • ACA - Adjacent Control Area
          • ASR - Aggregated System Resource
          • ECA - Embedded Control Area
        • ref - string - The reference name of the aggregation node.
        • startEffectiveDate* - timestamp - When the aggregation node assignment became effective.
        • endEffectiveDate* - timestamp - When the aggregation node assignment ended.
  • Where will you see it?
  • Description: A summary of usage for usage point for a specific period of time. This often represents a bill.
  • Fields:
    • billingPeriod - duration - The start and duration of the summary period (e.g. the bill start/end).
    • statusTimeStamp - timestamp - The issue time for the summary (e.g. the bill statement date).
    • billLastPeriod* - integer - The cost for the last bill, in hundred-thousandths of currency.
    • billToDate* - integer - The bill cost to date (if not over yet), in hundred-thousandths of currency.
    • costAdditionalLastPeriod* - integer - The total bill cost, in hundred-thousandths of currency.
    • costAdditionalDetailLastPeriod*† - object - A bill line item.
      • itemKind - enum - The type of line item.
        • 1 - Energy Generation Fee
        • 2 - Energy Delivery Fee
        • 3 - Energy Usage Fee
        • 4 - Administrative Fee
        • 5 - Tax
        • 6 - Energy Generation Credit
        • 7 - Energy Delivery Credit
        • 8 - Administrative Credit
        • 9 - Payment
        • 10 - Information
      • note - string - Line item name and/or description.
      • amount* - integer - Line item cost, in hundred-thousandths of currency.
      • rounding* - integer - How much the line item was rounded.
      • dateTime* - timestamp - The date for the line item.
      • measurement* - measurement - The measured line item reading value and units.
      • unitCost* - measurement - The line item rate, in hundred-thousandths of currency.
      • itemPeriod* - measurement - The start and duration of the line item.
    • currency* - enum - The currency of cost values in the summary.
      • 840 - USD
      • 978 - EUR
      • 36 - AUD
      • 124 - CAD
      • 756 - CHF
      • 156 - CNY
      • 208 - DKK
      • 826 - GBP
      • 392 - JPY
      • 578 - NOK
      • 643 - RUB
      • 752 - SEK
      • 356 - INR
      • 0 - other
    • overallConsumptionLastPeriod* - measurement - The total usage during the summary period.
    • currentBillingPeriodOverAllConsumption* - measurement - Total usage to date.
    • currentDayLastYearNetConsumption* - measurement - Usage a year ago today.
    • currentDayNetConsumption* - measurement - Today's net consumption.
    • currentDayOverallConsumption* - measurement - Today's overall consumption.
    • peakDemand* - measurement - Today's peak demand.
    • previousDayLastYearOverallConsumption* - measurement - Usage a year ago yesterday.
    • previousDayNetConsumption* - measurement - Yesterday's net consumption.
    • previousDayOverallConsumption* - measurement - Yesterday's overall consumption.
    • qualityOfReading* - enum - The quality of the summary readings.
      • 0 - valid
      • 7 - manually edited
      • 8 - estimated using reference day
      • 9 - estimated using linear interpolation
      • 10 - questionable
      • 11 - derived
      • 12 - projected (forecast)
      • 13 - mixed
      • 14 - raw
      • 15 - normalized for weather
      • 16 - other
      • 17 - validated
      • 18 - verified
      • 19 - revenue-quality
    • ratchetDemand* - measurement - The ratchet demand over the ratchet demand period.
    • ratchetDemandPeriod* - duration - The start and duration of the ratchet demand period.
    • commodity* - enum - The type of commodity being summarized.
      • 0 - none
      • 1 - electricity SecondaryMetered
      • 2 - electricity PrimaryMetered
      • 3 - communication
      • 4 - air
      • 5 - insulativeGas
      • 6 - insulativeOil
      • 7 - naturalGas
      • 8 - propane
      • 9 - potableWater
      • 10 - steam
      • 11 - wasteWater
      • 12 - heatingFluid
      • 13 - coolingFluid
      • 14 - nonpotableWater
      • 15 - nox
      • 16 - so2
      • 17 - ch4
      • 18 - co2
      • 19 - carbon
      • 20 - hch
      • 21 - pfc
      • 22 - sf6
      • 23 - tvLicence
      • 24 - internet
      • 25 - refuse
      • 26 - electricity TransmissionMetered
    • tariffProfile* - string - The tariff rate schedule for the summary.
    • readCycle* - string - The schedule on which this summary was generated.
    • tariffRiderRefs* - object - A list of tariff riders that are applied to this summary.
      • tariffRiderRef*† - object - A specific tariff rider.
        • riderType - string - The name or type of tariff rider.
        • enrollmentStatus - enum - The status of the rider.
          • unenrolled
          • enrolled
          • enrolledPending
        • effectiveDate - timestamp - When the rider became effective.
    • billingChargeSource* - object - The source of the billing charge.
      • agencyName* - string - The name of the billing source.
  • Where will you see it?
  • Description: A measurement of value for a specific unit and time.
  • Fields:
    • powerOfTenMultiplier* - enum - The power to multiply the value by to get the unit of measure.
      • -12 - Pico
      • -9 - Nano
      • -6 - Micro
      • -3 - Milli
      • -2 - Centi
      • -1 - Deci
      • 0 - None
      • 1 - Deca
      • 2 - Hecto
      • 3 - Kilo
      • 6 - Mega
      • 9 - Giga
      • 12 - Tera
    • timeStamp* - timestamp - The time of the measurement.
    • uom* - enum - The unit of measure.
      • 61 - VA
      • 38 - W
      • 63 - VAr
      • 71 - VAh
      • 72 - Wh
      • 73 - VArh
      • 29 - V
      • 30 - ohm
      • 5 - A
      • 25 - F
      • 28 - H
      • 23 - degC
      • 27 - sec
      • 159 - min
      • 160 - h
      • 9 - deg
      • 10 - rad
      • 31 - J
      • 32 - n
      • 53 - siemens
      • 0 - none
      • 33 - Hz
      • 3 - g
      • 39 - pa
      • 0 - none
      • 2 - m
      • 41 - m2
      • 42 - m3
      • 69 - A2
      • 105 - A2h
      • 70 - A2s
      • 106 - Ah
      • 152 - APerA
      • 103 - APerM
      • 68 - As
      • 79 - b
      • 113 - bm
      • 22 - bq
      • 132 - btu
      • 133 - btuPerH
      • 8 - cd
      • 76 - char
      • 75 - HzPerSec
      • 114 - code
      • 65 - cosTheta
      • 111 - count
      • 119 - ft3
      • 120 - ft3compensated
      • 123 - ft3compensatedPerH
      • 78 - gM2
      • 144 - gPerG
      • 21 - gy
      • 150 - HzPerHz
      • 77 - charPerSec
      • 130 - imperialGal
      • 131 - imperialGalPerH
      • 51 - jPerK
      • 165 - jPerKg
      • 6 - K
      • 158 - kat
      • 47 - kgM
      • 48 - kgPerM3
      • 134 - litre
      • 157 - litreCompensated
      • 138 - litreCompensatedPerH
      • 137 - litrePerH
      • 143 - litrePerLitre
      • 82 - litrePerSec
      • 156 - litreUncompensated
      • 139 - litreUncompensatedPerH
      • 35 - lm
      • 34 - lx
      • 49 - m2PerSec
      • 167 - m3compensated
      • 126 - m3compensatedPerH
      • 125 - m3PerH
      • 45 - m3PerSec
      • 166 - m3uncompensated
      • 127 - m3uncompensatedPerH
      • 118 - meCode
      • 7 - mol
      • 147 - molPerKg
      • 145 - molPerM3
      • 146 - molPerMol
      • 80 - money
      • 148 - mPerM
      • 46 - mPerM3
      • 43 - mPerSec
      • 44 - mPerSec2
      • 102 - ohmM
      • 155 - paA
      • 140 - paG
      • 141 - psiA
      • 142 - psiG
      • 100 - q
      • 161 - q45
      • 163 - q45h
      • 162 - q60
      • 164 - q60h
      • 101 - qh
      • 54 - radPerSec
      • 154 - rev
      • 4 - revPerSec
      • 149 - secPerSec
      • 11 - sr
      • 109 - status
      • 24 - sv
      • 37 - t
      • 169 - therm
      • 108 - timeStamp
      • 128 - usGal
      • 129 - usGalPerH
      • 67 - V2
      • 104 - V2h
      • 117 - VAhPerRev
      • 116 - VArhPerRev
      • 74 - VPerHz
      • 151 - VPerV
      • 66 - Vs
      • 36 - wb
      • 107 - WhPerM3
      • 115 - WhPerRev
      • 50 - wPerMK
      • 81 - WPerSec
      • 153 - WPerVA
      • 168 - WPerW
    • value* - integer - The measurement value.
    • readingTypeRef* - url - A reference link for the type of reading.
  • Where will you see it?
  • * Field is optional
  • † Field can appear multiple times in the object

UtilityAPI - Oakland, California - info@utilityapi.com