# Green Button Data
[](https://rubygems.org/gems/green-button-data)
[](https://circleci.com/gh/VerdigrisTech/green-button-data)
[](https://gemnasium.com/VerdigrisTech/green-button-data)
[](https://codeclimate.com/github/VerdigrisTech/green-button-data)
[](https://codecov.io/github/VerdigrisTech/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:
```ruby
gem 'green-button-data'
```
Then run Bundler:
```bash
$ 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:
```ruby
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:
```ruby
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
> **IMPORTANT:** Version 0.3.0 has a bug which causes Rails not to boot
correctly. Please use 0.3.1 or higher when integrating into Rails by
running `bundle update green-button-data`.
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](https://github.com/intridea/omniauth).
### List all entries
By default, the `.all` method attempts to use the URL path set by configuration:
```ruby
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:
```ruby
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:
```ruby
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`:
```ruby
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:
```ruby
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:
```ruby
# 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
1. Fork this project
2. Create a feature branch: `git checkout -b my-awesome-feature`
3. Make changes and commit: `git commit -am "Add awesome feature"`
4. Push the branch: `git push origin my-awesome-feature`
5. Submit a pull request
## Versioning
Green Button Data gem follows [Semantic Versioning 2.0](http://semver.org/). 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:
```ruby
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](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
license.
Verdigris Technologies Inc. assumes NO RESPONSIBILITY OR LIABILITY
UNDER ANY CIRCUMSTANCES for usage of this software. See the [LICENSE.txt](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
file for detailed legal information.
Copyright © 2015, [Verdigris Technologies Inc](http://verdigris.co). All rights reserved.