Skip to content

Latest commit

 

History

History
266 lines (183 loc) · 9.66 KB

README.rdoc

File metadata and controls

266 lines (183 loc) · 9.66 KB
Raw

Carbon ↑

Carbon is a Ruby API wrapper and command-line console for the Brighter Planet emission estimate web service, which is located at 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

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 will recognize. In this case, a review of the available characteristics for Automobile 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([...])
=> #<RentalCar [...]>
> my_emission = my_car.emission_estimate
=> #<Carbon::EmissionEstimate [...]>
> 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 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 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.

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 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 © 2011 Brighter Planet.