https://github.com/faradayio/carbon-old

Gem implementing Brighter Planet's emissions estimates API
https://github.com/faradayio/carbon-old

Last synced: 10 months ago
JSON representation

Gem implementing Brighter Planet's emissions estimates API

• Host: GitHub
• URL: https://github.com/faradayio/carbon-old
• Owner: faradayio
• License: mit
• Created: 2010-04-22T20:15:36.000Z (about 16 years ago)
• Default Branch: master
• Last Pushed: 2012-02-25T01:04:25.000Z (over 14 years ago)
• Last Synced: 2025-06-11T08:09:48.200Z (about 1 year ago)
• Language: Ruby
• Homepage:
• Size: 1.05 MB
• Stars: 7
• Watchers: 3
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.rdoc
  • License: MIT-LICENSE.txt

Awesome Lists containing this project

README

          
= Carbon

Carbon is a Ruby API wrapper and command-line console for the {Brighter Planet emission estimate web service}[http://carbon.brighterplanet.com], which is located at http://carbon.brighterplanet.com. By querying the web service, it can estimate the carbon emissions of many real-life objects, such as cars and houses, based on particular attributes that they may have.

Full documentation: {RDoc}[http://rdoc.info/projects/brighterplanet/carbon]

== Quick start 1: experimenting with the console

You'll need a Brighter Planet API key. See the "API keys" section below for details.

First get the gem:

    $ gem install carbon

Then start the console:

    $ carbon

    carbon->

Provide your key:

    carbon-> key '123ABC'

      => Using key 123ABC

      

Start a flight calculation:

    carbon-> flight

      => 1210.66889895298 kg CO2e

    flight*>

Start providing characteristics:

    flight*> origin_airport 'jfk'

      => 1593.46008200024 kg CO2e

    flight*> destination_airport 'lax'

      => 1766.55536727522 kg CO2e

Review what you've entered:

    flight*> characteristics

      => origin_airport: jfk

         destination_airport: lax

See how the calculation's being made:

    flight*> methodology

      => emission: from fuel and passengers with coefficients

         [ ... ]

         cohort: from t100

         

See intermediate calculations:

    flight*> reports

      => emission: 1766.55536727522

         [ ... ]

         cohort: {"members"=>262}

Generate a methodology URL:

    flight*> url

      => http://carbon.brighterplanet.com/flights.json?origin_airport=jfk&destination_airport=lax&key=123ABC

And when you're done:

    flight*> done

      => Saved as flight #0

    carbon->

You can recall this flight anytime during this same session:

    carbon-> flight 0

      => 1766.55536727522 kg CO2e

    flight*> characteristics

      => origin_airport: jfk

         destination_airport: lax

         

For more, see the "Console" section below.

== Quick start 2: using the library in your application

You'll need a Brighter Planet API key. See the "API keys" section below for details.

First get the gem:

    $ gem install carbon

Carbon works by extending any Ruby class you're using to represent an emission source. For instance, let's say you have a Ruby class RentalCar that represents a rental car on your lot. (Note that ActiveRecord models work great with this gem.)

    class RentalCar

      attr_accessor :model, :model_year, :fuel_economy

      class Make

        attr_accessor :name

        def to_param

          name

        end

      end

      def make

        @make ||= Make.new

      end

    end

In order to calculate carbon emissions, we need to map the car's relevant attributes to characteristics that the {web service}[http://carbon.brighterplanet.com] will recognize. In this case, a review of the available characteristics for Automobile[http://carbon.brighterplanet.com/automobiles/options] yields the following map:

    class RentalCar

      # [...]

      include Carbon

      emit_as :automobile do

        provide :make

        provide :model

        provide :model_year

        provide :fuel_economy, :as => :fuel_efficiency

      end

    end

When you want to calculate emissions, simply call RentalCar#emission_estimate.

    > my_car = RentalCar.new([...])

    => #

    > my_emission = my_car.emission_estimate

    => #

    > my_emission.to_f

    => 4919.2

    > my_emission.emission_units

    => "kilograms"

    > my_emission.methodology

    => "http://carbon.brighterplanet.com/automobiles.html?[...]"

== API keys

You should get an API key from http://keys.brighterplanet.com and set it globally:

    Carbon.key = '12903019230128310293'

Now all of your queries will use that key.

== Timeframes and 0.0kg results

You submit this query about a flight in 2009, but the result is 0.0 kilograms. Why?

  $ carbon 

  carbon-> flight

  [...]

  flight*> date '2009-05-03'

    => 0.0 kg CO2e

  flight*> url

    => http://carbon.brighterplanet.com/flights.json?date=2009-05-03

It's telling you that a flight in 2009 did not result in any 2011 emissions (the default timeframe is the current year).

  flight*> timeframe '2009'

    => 847.542137647608 kg CO2e

  flight*> url

    => http://carbon.brighterplanet.com/flights.json?date=2009-05-03&timeframe=2009-01-01/2010-01-01

So, 850 kilograms emitted in 2009.

== Association serialization

Your objects' attributes are serialized via #to_characteristic or #to_param (in that order of preference) before being submitted to the web service. 

For example:

    class RentalCar < ActiveRecord::Base

      belongs_to :automobile_make

      emit_as :automobile do

        provide :automobile_make, :as => :make

      end

    end

    

    class AutomobileMake < ActiveRecord::Base # schema includes :name

      has_many :rental_cars

      alias :to_characteristic :name

    end

    

Without AutomobileMake#to_characteristic, the library would have no way of knowing how to serialize.

== Using timeouts

    > RentalCar.new.emission_estimate :timeout => 100

    

Runs a realtime request but allows timing out the network call. Raises Timeout::Error if timeout is exceeded.

== Certified calculations

You can run {certified calculations}[http://brighterplanet.com/certified] by setting certified to true.

    > RentalCar.new.emission_estimate :certified => true

== Persisted queries

You can specify that the result be persisted in low-latency storage so that future identical requests can use the same estimate:

    > RentalCar.new.emission_estimate :guid => 'A_GLOBALLY_UNIQUE_IDENTIFIER_FOR_THIS_EMISSION_ESTIMATE'

== Asynchronous queries

=== Using a callback

To specify that the result of a query should be POSTed back to you, simply pass an URL as the :callback option to #emission_estimate:

    > RentalCar.new.emission_estimate :callback => 'http://example.com/my/callback/handler'

A good way to test this is to set up a {PostBin}[http://postbin.org].

=== Using polling

By combining :guid and :defer => true, you can poll for a result:

    > batmobile.emission_estimate :guid => '[...]', :defer => true

    # Do other things . . . and then:

    > batmobile.emission_estimate :guid => '[...]'

If the result isn't available by the time you want it, a standard synchronous estimate will be provided.

== Exceptions

Since this gem connects to a web service, you need to be ready for network problems and latency. For example:

    begin

      my_emission = my_car.emission_estimate

    rescue ::SocketError, ::EOFError, ::Timeout::Error, ::Errno::ETIMEDOUT, ::Errno::ENETUNREACH, ::Errno::ECONNRESET, ::Errno::ECONNREFUSED

      # These are general network errors raised by Net::HTTP.

      # Your internet connection might be down.

    rescue ::Carbon::RateLimited

      # In order to prevent denial-of-service attacks, our servers limit request rates.

      # The gem will try up to three times to get an answer back from the server, waiting slightly longer each time.

      # If you still get this exception, please contact us at staff@brighterplanet.com and we'll lift your rate.

    rescue ::Carbon::RealtimeEstimateFailed

      # Our server returned a 4XX or 5XX error.

      # Please contact us at staff@brighterplanet.com.

    rescue ::Carbon::QueueingFailed

      # The gem connects directly to Amazon SQS in order to provide maximum throughput. If that service returns anything other than success, you get this exception.

      # Please contact us at staff@brighterplanet.com.

    end

    

== Console

This library includes a special console for performing calculations interactively. Quick Start #1 provides an example session. Here is a command reference:

=== Shell mode

[+help+]                           Displays a list of emitter types.

[+key+ _yourkey_]                  Set the {developer key}[http://keys.brighterplanet.com] that should be used for this session. Alternatively, put this key in ~/.brighter_planet and it will be auto-selected on console startup.

[+_emitter_type_+]                 (e.g. +flight+) Enters emitter mode using this emitter type.

[emitter_type num] (e.g. flight 0) Recalls a previous emitter from this session.

[+exit+]                           Quits.

  

=== Emitter mode

In Emitter mode, the prompt displays the emitter type in use. If a timeframe has been set, the timeframe is also included in the prompt.

[+help+]                               Displays a list of characteristics for this emitter type.

[characteristic value] (e.g. origin_airport 'lax') Provide a characteristic. Remember, this is Ruby we're dealing with, so strings must be quoted.

[+timeframe+]                          Display the current timeframe in effect on the emission estimate.

[timeframe timeframe]  (e.g. timeframe '2009-01-01/2010-01-01' or just timeframe '2009') Set a timeframe on the emission estimate.

[+emission+]                           Displays the current emission in kilograms CO2e for this emitter.

[+lbs+, +pounds+, or +tons+]           Display the emission using different units.

[+characteristics+]                    Lists the characteristics you have provided so far.

[+methodology+]                        Summarizes how the calculation is being made.

[+reports+]                            Displays intermediate calculations that were made in pursuit of the emission estimate.

[+url+]                                Generates a methodology URL suitable for pasting into your browser for further inspection.

[+done+]                               Saves this emitter and returns to shell mode.

== Copyright

Copyright (c) 2011 Brighter Planet.