Gem implementing Brighter Planet's emissions estimates API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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

Provide your key:

carbon-> key '123ABC'
  => Using key 123ABC

Start a flight calculation:

carbon-> flight
  => 1210.66889895298 kg CO2e

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

And when you're done:

flight*> done
  => Saved as flight #0

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
  def make
    @make ||=

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

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

> my_car =[...])
=> #<RentalCar [...]>
> my_emission = my_car.emission_estimate
=> #<Carbon::EmissionEstimate [...]>
> my_emission.to_f
=> 4919.2
> my_emission.emission_units
=> "kilograms"
> my_emission.methodology
=> "[...]"

API keys

You should get an API key from 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

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

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

class AutomobileMake < ActiveRecord::Base # schema includes :name
  has_many :rental_cars
  alias :to_characteristic :name

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

Using timeouts

> :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.

> :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:


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:

> :callback => ''

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.


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

  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 and we'll lift your rate.
rescue ::Carbon::RealtimeEstimateFailed
  # Our server returned a 4XX or 5XX error.
  # Please contact us at
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


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

Shell mode


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.


(e.g. flight) Enters emitter mode using this emitter type.

emitter_type num

(e.g. flight 0) Recalls a previous emitter from this session.



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.


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.


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.


Displays the current emission in kilograms CO2e for this emitter.

lbs, pounds, or tons

Display the emission using different units.


Lists the characteristics you have provided so far.


Summarizes how the calculation is being made.


Displays intermediate calculations that were made in pursuit of the emission estimate.


Generates a methodology URL suitable for pasting into your browser for further inspection.


Saves this emitter and returns to shell mode.


Copyright © 2011 Brighter Planet.