1. Documentation
  2. Green Button
  3. API Docs

Green Button API Documentation

In addition to our JSON API we offer a Green Button REST API (technically called OpenESPI) for downloading the utility data you've been authorized by utility customers. This API is how you download Green Button XML formatted data, so you generally want to use this if you already have the ability to ingest that type of xml format.

The Green Button standard specifies three levels of access_tokens that are used to access various parts of the API.

To make an authenticated API request with one of these access tokens, simply add it as an Authorization: Bearer <token_here> header in the API request. For example, below is an example curl request with an access token in the header. 

curl \
-H "Authorization: Bearer a2e7fd6a0c2f474c9a63ec18321c9989f805868237b14d1e9029948a2d797121" \
https://utilityapi.com/DataCustodian/espi/1_1/resource/ReadServiceStatus
  • Description: Get your list of Authorizations from customers.
  • Authentication: client_access_token
  • Response: <feed> containing Authorization entries (could be empty feed if no authorizations).
  • When should you use this endpoint?
    • Getting your list of authorizations and their statuses.
  • Description: Get the list of UsagePoints (e.g. meters) for an authorization.
  • Authentication: access_token
  • Response: <feed> containing UsagePoint entries (could be empty feed if no usage points).
  • When should you use this endpoint?
    • When you want to get the meter list for a particular authorization.
  • Description: Get a specific UsagePoint (e.g. meter).
  • Authentication: access_token
  • Response: <entry> containing a UsagePoint object.
  • When should you use this endpoint?
    • When you want get the related urls for a particular meter.
  • Description: Get the list of MeterReadings for a specific meter.
  • Authentication: access_token
  • Response: <feed> containing MeterReading entries (could be empty feed if no readings).
  • When should you use this endpoint?
    • When you want to get the list of meter readings for a particular meter.
  • Description: Get a specific MeterReading for a meter.
  • Authentication: access_token
  • Response: <entry> containing a MeterReading object.
  • When should you use this endpoint?
    • When you want get the related urls for a particular meter reading.
  • Description: Get the list of IntervalBlocks for a specific meter reading.
  • Authentication: access_token
  • Response: <feed> containing IntervalBlock entries (could be empty feed if no intervals).
  • When should you use this endpoint?
    • When you want to get the list of intervals for a specific meter reading.
  • Description: Get a specific IntervalBlock for a meter reading.
  • Authentication: access_token
  • Response: <entry> containing a IntervalBlock object.
  • When should you use this endpoint?
    • When you want get a specific block of intervals.
  • Description: Get the list of UsageSummaries (e.g. bills) for a meter.
  • Authentication: access_token
  • Response: <feed> containing UsageSummary entries (could be empty feed if no bills).
  • When should you use this endpoint?
    • When you want to get the list of bills for a specific meter.
  • Description: Get a specific UsageSummary (e.g. bill) for a meter.
  • Authentication: access_token
  • Response: <entry> containing a UsageSummary object.
  • When should you use this endpoint?
    • When you want get a specific bill.
  • Description: List all of the available Customers.
  • Authentication: access_token
  • Response: <feed> containing Customer entries (could be empty feed if no customers).
  • When should you use this endpoint?
  • Description: List all of the available Meter.
  • Authentication: access_token
  • Response: <feed> containing Meter entries (could be empty feed if no meters).
  • When should you use this endpoint?
  • Description: Get a specific Meter.
  • Authentication: access_token
  • Response: <entry> containing a Meter object.
  • When should you use this endpoint?
  • Description: List all of the available EndDevice.
  • Authentication: access_token
  • Response: <feed> containing EndDevice entries (could be empty feed if no end devices).
  • When should you use this endpoint?
  • Description: Get a feed with all data (usage points, usage summaries, interval blocks, etc.) for a specific Authorization.
  • Authentication: access_token
  • Query Parameters:
    • published-min=YYYY-MM-DDTHH:MM:SSZ - Only include data after a specific time.
    • published-max=YYYY-MM-DDTHH:MM:SSZ - Only include data before a specific time.
    • updated-min=YYYY-MM-DDTHH:MM:SSZ - Only include data added to the API after a specific time.
    • updated-max=YYYY-MM-DDTHH:MM:SSZ - Only include data added to the API before a specific time.
  • Response: <feed> containing UsagePoint, LocalTimeParameters, MeterReading, ReadingType, IntervalBlock, UsageSummary, and ElectricPowerQualitySummary entries.
  • When should you use this endpoint?
    • When you want all the data under an authorization.
    • When you want all the data within a certain time range (using the published-min/published-max parameters).
    • When you want all the data since you last checked (using the updated-min/updated-max parameters).
  • Example url with query parameter:
    https://.../Batch/Subscription/11111?published-min=2018-08-01T00:00:00Z
  • Notes:
    • This feed can get pretty huge, so you probably want to always use at least the published-min or updated-min query parameters so you're not always downloading a ton of data you already have.
    • This feed could be empty feed if there are no usage points under an authorization or the usage points aren't valid inside the time ranges specified by your query parameters.
    • This feed could be missing sub-resources (IntervalBlocks, etc.) if data for those don't exist or fall outside of the time ranges you specified in your query parameters.
    • If your request will take too long for us to respond synchronously, you may get a 202 HTTP response as we build a cache for the response. Just keep requesting according to the Retry-After header in the 202 response and we'll eventually return a 200 HTTP response with the feed data.
  • Description: Get a feed with all data (usage summaries, interval blocks, etc.) for a specific UsagePoint.
  • Authentication: access_token
  • Query Parameters:
    • published-min=YYYY-MM-DDTHH:MM:SSZ - Only include data after a specific time.
    • published-max=YYYY-MM-DDTHH:MM:SSZ - Only include data before a specific time.
    • updated-min=YYYY-MM-DDTHH:MM:SSZ - Only include data added to the API after a specific time.
    • updated-max=YYYY-MM-DDTHH:MM:SSZ - Only include data added to the API before a specific time.
  • Response: <feed> containing the UsagePoint, LocalTimeParameters, MeterReading, ReadingType, IntervalBlock, UsageSummary, and ElectricPowerQualitySummary entries.
  • When should you use this endpoint?
    • When you want all the data under a usage point (e.g. meter).
    • When you want all the data within a certain time range (using the published-min/published-max parameters).
    • When you want all the data since you last checked (using the updated-min/updated-max parameters).
  • Example url with query parameter:
    https://.../Batch/Subscription/11111/UsagePoint/22222?published-min=2018-08-01T00:00:00Z
  • Notes:
    • This feed can get pretty big, so you probably want to always use at least the published-min or updated-min query parameters so you're not always downloading a ton of data you already have.
    • This feed could be empty feed if the usage point isn't valid inside the time ranges specified by your query parameters.
    • This feed could be missing sub-resources (IntervalBlocks, etc.) if data for those don't exist or fall outside of the time ranges you specified in your query parameters.
    • If your request will take too long for us to respond synchronously, you may get a 202 HTTP response as we build a cache for the response. Just keep requesting according to the Retry-After header in the 202 response and we'll eventually return a 200 HTTP response with the feed data.
  • Description: Bulk feeds you get linked to from notifications.
  • Authentication: client_access_token
  • Response: <feed> containing the entries intended to be delivered to the third party. This is usually a mix of new authorizations and new usage summaries and interval blocks for usage points with updated data.
  • When should you use this endpoint?
    • When you get a notification with a bulk download entry.
  • Notes:
    • Bulk urls you receive from notifications are only available for download for a few days, so you should probably save them on your side since you may not be able to download them again later.
    • Bulk feeds are usually used to deliver updated or bulk payloads of data. They may contain data from multiple authorizations, so you need to pay close attention to each entry's links to know where that entry belongs.
    • Bulk payloads can get pretty huge, so we recommend downloading first to a safe location, then processing it afterwards. That way, if you run out of memory processing the data, you still have the payload saved on your end.
  • Description: Check the status of the Green Button API.
  • Authentication: client_access_token
  • Response: A ServiceStatus object.
  • When should you use this endpoint?
    • When you want to check on the status of the API.
  • Notes:
    • You also need to be aware of the various error and maintenance HTTP response codes that we may respond with on the API, including for the status endpoint.
Code Response Format Description
200 Atom XML Successful request. If a single resource endpoint (i.e. the url ends with a uid), will be an Atom XML <entry>. If listing multiple objects (e.g. the url doesn't end with a uid), will be an Atom XML <feed>.
202 Empty Request is too large to be synchronous, so building a cache asynchronously. See Retry-After header for how long to wait before trying again.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param - One of the query parameters was invalid. Check the error description for more info.
  • ... - We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid, expired, or missing access token. See our docs on Authentication for which types of access tokens to use where.
403 Error The access token you are using is not the correct type for this endpoint. See our docs on Authentication for which types of access tokens to use where.
404 Error This endpoint doesn't exist or you don't have permissions to see it.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).

UtilityAPI - Oakland, California - info@utilityapi.com