Green Button Data

Green Button Data is a Ruby gem that can consume Green Button APIs and parse the Green Button data XML schema very quickly. It uses an event-driven SAX parser which parses XML data without building an entire DOM in memory.

Getting Started

Add the Green Button Data gem to your Gemfile:

gem 'green-button-data'

Then run Bundler:

$ bundle

Unless you have a project that auto loads all gems in the Gemfile (e.g. a Rails project), you will need to require it:

require 'green-button-data'

This will expose the GreenButtonData module namespace.

Integrating GreenButtonData Into Your Application

GreenButtonData gem provides a familiar interface to consuming API endpoints. Method names are similar to Rails' ActiveRecord models and can be easily integrated into existing applications.

Configuration

You can add configuration options like the following:

GreenButtonData.configure do |config|
  config.base_url = "https://api.example.com/DataCustodian/espi/1_1/resource/"
  config.application_information_path = "ApplicationInformation/"
  config.authorization_path = "Authorization/"
  config.subscription_path = "Subscription/"
  config.usage_point_path = "UsagePoint/"
end

Note that each path must end with a trailing slash.

Rails Integration

If you are developing a Rails app, create a file at config/initializers/green_button_data.rb from your Rails project root and add the configuration there.

Green Button Data API Client

Green Button Data specification states that all API endpoints be secured with OAuth2 which means most fetch operations will require auth tokens.

Some endpoints are secured further by utilizing client SSL certificates (e.g. Pacific Gas & Electric). You may pass in ssl options in addition to the token option in this case.

DISCLAIMER: Green Button Data is NOT responsible for managing OAuth tokens to make authenticated requests. There are other gems that provide mature, production proven OAuth 2 functionalities such as OmniAuth.

List all entries

By default, the .all method attempts to use the URL path set by configuration:

require 'green-button-data'

# Ideally obtained from OmniAuth gem
access_token = "12345678-1024-2048-abcdef001234"

# Return all usage points; URL is specified in GreenButtonData.configuration.usage_point_url
usage_points = UsagePoint.all token: access_token

You may override the global configuration by specifying the URL in the method:

usage_points = UsagePoint.all "https://someotherapi.org/espi/Authorization",
                              token: access_token

Find an entry by ID

If you have URL defined in configuration, the .find method appends the ID to the URL:

GreenButtonData.configure do |config|
  config.base_url = "https://services.greenbuttondata.org/"
  config.usage_point_path = "DataCustodian/espi/1_1/resource/UsagePoint/"
end

# GET request to https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/UsagePoint/2
usage_point = GreenButtonData::UsagePoint.find 2, token: access_token

As with .all method, URL can be overridden per request in .find:

usage_point = GreenButtonData::UsagePoint.find "https://someotherapi.org/espi/UsagePoint/1",
                                               token: access_token

Parsing

Almost all of the functionality for parsing data is wrapped in the GreenButtonData::Feed class.

To parse a Green Button Atom feed, simply call the parse method and pass in the entire XML document:

require 'green-button-data'

xml_text = File.read "#{File.dirname __FILE__}/gb_example_interval_block.xml"
data = GreenButtonData::Feed.parse xml_text

You can then access the data like this:

# Print all the interval readings from the feed
data.entries.each do |entry|
  p "Entry: #{entry.title}"
  entry.content.interval_block.interval_readings.each do |reading|
    time_period = reading.time_period
    p "[#{time_period.starts_at} - #{time_period.ends_at}]: #{reading.value}"
  end
end

Contributing

Fork this project
Create a feature branch: git checkout -b my-awesome-feature
Make changes and commit: git commit -am "Add awesome feature"
Push the branch: git push origin my-awesome-feature
Submit a pull request

Versioning

Green Button Data gem follows Semantic Versioning 2.0. As such, you can specify a pessimistic version constraint on this gem with two digits of precision and be guaranteed latest features and bug fixes without backwards breaking changes:

gem 'green-button-data', '~> 0.1'

Exception to this rule as per the SemVer specification is major version zero for initial development. This gem's API should NOT be considered stable until 1.0 release.

License

This software is distributed AS IS WITHOUT WARRANTY under Simplified BSD license.

Verdigris Technologies Inc. assumes NO RESPONSIBILITY OR LIABILITY UNDER ANY CIRCUMSTANCES for usage of this software. See the LICENSE.txt file for detailed legal information.