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: Represents the person or organization receiving services from a supplier.
  • Fields:
    • kind* - enum - The kind of customer
      • residential - Residential customer
      • residentialAndCommercial - Residential and commercial customer
      • residentialAndStreetlight - Residential and streetlight customer
      • residentialStreetlightOthers - Residential streetlight or other related customer
      • residentialFarmService - Residential farm service customer
      • commercialIndustrial - Commercial industrial customer
      • pumpingLoad - Pumping load customer
      • windMachine - Wind machine customer
      • energyServiceSupplier - Customer as energy service supplier
      • energyServiceScheduler - Customer as energy service scheduler
      • enterprise - Represents the owning enterprise
      • regionalOperator - Represents a local operator of a larger enterprise
      • subsidiary - A subsidiary of a larger enterprise
      • internalUse - An internal use customer
      • other - Other kind of customer
    • specialNeed* - string - Special service needs such as life support, hospitals, etc.
    • vip* - boolean - True if this is an important customer
    • pucNumber* - string - Public Utilities Commision (PUC) identification number
    • status* - status - The status of this customer
    • priority* - object - The priority of this customer
      • value* - string - The priority value at the specified time
      • dateTime* - timestamp - Date and time when the priority applies
      • remark* - string - Information relevant to the current priority
      • reason* - string - Reason code or explanation for the current priority
    • locale* - string - Locale designating the language used by this customer
    • customerName* - string - The name of this customer
  • Where will you see it?
  • Description: A grouping of products and services purchased by a customer.
  • Fields:
    • type* - string - Document classification string
    • authorName* - string - The name of the document's author
    • createdDateTime* - timestamp - When the document was created
    • lastModifiedDateTime* - timestamp - When the document was most recently modified
    • revisionNumber* - string - The current revision number of the document
    • electronicAddress* - electronic address - An electronic address for this document
    • subject* - string - The subject of the document
    • title* - string - The title of the document
    • docStatus* - status - The status of the document itself, e.g. draft, approved, etc.
    • status* - status - The status of the document's subject
    • comment* - string - A free-text comment
    • billingCycle* - string - Day when the customer account will be billed
    • budgetBill* - string - Budget bill code
    • lastBillAmount* - int - The final amount to be billed to the customer before the account is shut off
    • notifications*† - object - A customer account notification
      • methodKind - enum - The method by which the customer was notified
        • call - Notified by a telephone call
        • email - Notified by an email message
        • letter - Notified by a letter
        • other - Notified by some other means
        • ivr - Notified by an Interactive Voice Response system
      • time - timestamp - Date and time when the notification was sent
      • note - string - Annotation of the notification reason
      • customerNotificationKind - string - The type of notification (delinquincy, move-in, etc.)
    • contactInfo* - object - Contact information for the person responsible for this account
      • streetAddress* - address - The street address
      • postalAddress* - address - The postal address, may be different from streetAddress
      • phone1* - phone number - Phone number of the customer
      • phone2* - phone number - Alternate phone number of the customer
      • electronicAddress* - electronic address - An electronic address for the customer
      • organisationName* - string - The name of the customer's organization
    • accountId* - string - Identifier string for this customer account
  • Where will you see it?
  • Description: An agreement between the customer and the supplier to pay for service at a specific location.
  • Fields:
    • type* - string - Document classification string
    • authorName* - string - The name of the document's author
    • createdDateTime* - timestamp - When the document was created
    • lastModifiedDateTime* - timestamp - When the document was most recently modified
    • revisionNumber* - string - The current revision number of the document
    • electronicAddress* - electronic address - An electronic address for this document
    • subject* - string - The subject of the document
    • title* - string - The title of the document
    • docStatus* - status - The status of the document itself, e.g. draft, approved, etc.
    • status* - status - The status of the document's subject
    • comment* - string - A free-text comment
    • signDate* - timestamp - When the agreement was signed
    • validityInterval* - object - How long the agreement is valid
      • duration* - integer - The duration of the agreement
      • start* - timestamp - When the agreement goes into effect
    • loadMgmt* - string - Load management code
    • isPrePay* - boolean - True if the customer pays in advance for service
    • shutOffDateTime* - timestamp - Final date and time the service will be billed
    • DemandResponseProgram*† - object - Demand response program this customer is enrolled in
      • programName* - string - The name of the program
      • enrollmentStatus* - enum - Status of the customer's enrollment in the program
        • unenrolled - Not currently enrolled in the Demand Response program
        • enrolled - Currently enrolled in the Demand Response program
        • enrolledPending - Currently pending enrollment in the Demand Response program
      • programDescription* - url - A link to the program's description
      • programDate*† - object - Any enrollment or termination dates for the program
        • programDate* - timestamp - The enrollment or termination date
        • programDateDescription* - string - Description of the date (Enrollment, Termination, etc.)
      • capacityReservationLevel* - measurement - Measurement of capacity reserved
      • DRProgramNomination* - measurement - Measurement of demand response
    • PricingStructures*† - url - All pricing structures applicable to this agreement
    • currency* - enum - The currency used for all monetary amounts in this agreement
      • 840 - US dollar (USD)
      • 978 - European Euro (EUR)
      • 36 - Australian Dollar (AUD)
      • 124 - Canadian Dollar (CAD)
      • 756 - Swiss Franc (CHF)
      • 156 - Chinese Yuan Renminbi (CNY)
      • 208 - Danish Crown (DKK)
      • 826 - British Pound (GBP)
      • 392 - Japanese Yen (JPY)
      • 578 - Norwegian Crown (NOK)
      • 643 - Russian Ruble (RUB)
      • 752 - Swedish Crown (SEK)
      • 356 - Indian Rupee (INR)
      • 0 - Other
    • futureStatus* - status - The known future status of this agreement
    • agreementId* - string - Identifier for this agreement
  • Where will you see it?
  • Description: The physical object that measures consumption and detects events.
  • Fields:
    • type* - string - Utility-specific classification
    • utcNumber* - string - Uniquely Tracked Commodity number
    • serialNumber* - string - Serial number of the meter
    • lotNumber* - string - Lot number of the meter
    • purchasePrice* - string - The purchase price of the meter
    • critical* - boolean - True if the meter is considered critical
    • electronicAddress* - electronic address - The electronic address of the meter
    • lifecycle* - object - Lifecycle dates for this meter
      • manufacturedDate* - timestamp - Date the meter was manufactured
      • purchaseDate* - timestamp - Date the meter was purchased
      • receivedDate* - timestamp - Date the meter was received and place into inventory
      • installationDate* - timestamp - Date the meter was installed
      • removalDate* - timestamp - Date the meter was removed
      • retiredDate* - timestamp - Date the meter was retired
    • acceptanceTest* - object - Information about an acceptance test
      • type* - string - The type of test performed
      • success* - boolean - True if the meter passed this test
      • dateTime* - timestamp - When the asset was tested
    • initialCondition* - string - Condition at time of installation (new, rebuilt, etc.)
    • initialLossOfLife* - percent - Percentage of expected life vs when it was new; zero for new meters
    • isVirtual* - boolean - True if there is no physical device
    • isPan* - boolean - True if this is a Premises Area Network (PAN) device
    • installCode* - string - The installation code
    • amrSystem* - string - Automated Meter Reading (AMR) or other system used to communicate with this meter
    • formNumber* - string - Meter form designation describing what the meter is for
    • MeterMultipliers*† - object - Multipliers applied at this meter
      • kind* - enum - Kind of multiplier
        • kH - Meter watt-hour constant
        • transformerRatio - The ratio of a transformer's primary and secondary windings
        • kR - Register multiplier
        • kE - Test constant
        • ctRatio - Current transformer ratio
        • ptRatio - Potential transformer ratio
      • value* - float - The multiplier value
    • intervalLength* - int - The current interval duration in seconds
  • Where will you see it?
  • 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?

<ServiceSupplier>

  • 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: Information about an electronic address, for example a website.
  • Fields:
    • lan* - string - Address on local area network
    • mac* - string - MAC address
    • email1* - string - Primary email address
    • email2* - string - Alternate email address
    • web* - string - World Wide Web address
    • radio* - string - Radio address
    • userID* - string - User ID needed to log in
    • password* - string - Password needed to log in
  • 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?
  • Description: Address information for a location
  • Fields:
    • streetDetail* - object - The street portion of the address
      • number* - string - Location on the street
      • name* - string - The name of the street
      • suffix* - string - Suffix of the street name (North, West, etc.)
      • prefix* - string - Prefix of the street name (North, West, etc.)
      • type* - string - Type of street (boulevard, street, etc.)
      • code* - string - Reference number or code for the street
      • buildingName* - string - The name of the building containing the address
      • suiteNumber* - string - The number of the apartment or suite
      • addressGeneral* - string - First line of a free-form address or additional information
      • addressGeneral2* - string - Second line of a free-form address or additional information
      • addressGeneral3* - string - Third line of a free-form address or additional information
      • withinTownLimits* - boolean - True if this address is within the specified town
    • townDetail* - object - The town where the address is located
      • code* - string - A town code
      • section* - string - The town section
      • name* - string - The name of the town
      • county* - string - The county the town belongs to
      • stateOrProvince* - string - The state or province the town belongs to
      • country* - string - The country the town belongs to
    • status* - status - The town where the address is located
    • postalCode* - string - The postal code
    • poBox* - string - The Post Office box number
  • Where will you see it?

<Status>

  • Description: Information about the status of an object
  • Fields:
    • value* - string - The status value at the specified time
    • dateTime* - timestamp - Date and time when the status applies
    • remark* - string - Information relevant to the current status
    • reason* - string - Reason code or explanation for the current status
  • Where will you see it?
  • Description: Information about a telephone number.
  • Fields:
    • countryCode* - string - The ITU country code
    • areaCode* - string - The area or region code
    • cityCode* - string - The city code
    • localNumber* - string - The local part of the number
    • ext* - string - The extension
    • dialOut* - string - Dial out code
    • internationalPrefix* - string - The international dialling prefix
    • ituPhone* - string - The number in ITU E.164 format
  • Where will you see it?
  • * Field is optional
  • † Field can appear multiple times in the object

UtilityAPI - Oakland, California - info@utilityapi.com