{"id":24698647,"url":"https://github.com/faradayio/carbon-old","last_synced_at":"2025-08-20T04:04:10.092Z","repository":{"id":879792,"uuid":"624129","full_name":"faradayio/carbon-old","owner":"faradayio","description":"Gem implementing Brighter Planet's emissions estimates API","archived":false,"fork":false,"pushed_at":"2012-02-25T01:04:25.000Z","size":1106,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-11T08:09:48.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faradayio.png","metadata":{"files":{"readme":"README.rdoc","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-04-22T20:15:36.000Z","updated_at":"2020-09-10T18:52:45.000Z","dependencies_parsed_at":"2022-07-18T14:47:33.363Z","dependency_job_id":null,"html_url":"https://github.com/faradayio/carbon-old","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/faradayio/carbon-old","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon-old","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon-old/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon-old/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon-old/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faradayio","download_url":"https://codeload.github.com/faradayio/carbon-old/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon-old/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271262664,"owners_count":24728979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-27T04:29:40.891Z","updated_at":"2025-08-20T04:04:10.035Z","avatar_url":"https://github.com/faradayio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Carbon\n\nCarbon 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.\n\nFull documentation: {RDoc}[http://rdoc.info/projects/brighterplanet/carbon]\n\n== Quick start 1: experimenting with the console\n\n\u003cb\u003eYou'll need a Brighter Planet API key. See the \"API keys\" section below for details.\u003c/b\u003e\n\nFirst get the gem:\n\n    $ gem install carbon\n\nThen start the console:\n\n    $ carbon\n    carbon-\u003e\n\nProvide your key:\n\n    carbon-\u003e key '123ABC'\n      =\u003e Using key 123ABC\n      \nStart a flight calculation:\n\n    carbon-\u003e flight\n      =\u003e 1210.66889895298 kg CO2e\n    flight*\u003e\n\nStart providing characteristics:\n\n    flight*\u003e origin_airport 'jfk'\n      =\u003e 1593.46008200024 kg CO2e\n    flight*\u003e destination_airport 'lax'\n      =\u003e 1766.55536727522 kg CO2e\n\nReview what you've entered:\n\n    flight*\u003e characteristics\n      =\u003e origin_airport: jfk\n         destination_airport: lax\n\nSee how the calculation's being made:\n\n    flight*\u003e methodology\n      =\u003e emission: from fuel and passengers with coefficients\n         [ ... ]\n         cohort: from t100\n         \nSee intermediate calculations:\n\n    flight*\u003e reports\n      =\u003e emission: 1766.55536727522\n         [ ... ]\n         cohort: {\"members\"=\u003e262}\n\nGenerate a methodology URL:\n\n    flight*\u003e url\n      =\u003e http://carbon.brighterplanet.com/flights.json?origin_airport=jfk\u0026destination_airport=lax\u0026key=123ABC\n\nAnd when you're done:\n\n    flight*\u003e done\n      =\u003e Saved as flight #0\n    carbon-\u003e\n\nYou can recall this flight anytime during this same session:\n\n    carbon-\u003e flight 0\n      =\u003e 1766.55536727522 kg CO2e\n    flight*\u003e characteristics\n      =\u003e origin_airport: jfk\n         destination_airport: lax\n         \nFor more, see the \"Console\" section below.\n\n== Quick start 2: using the library in your application\n\n\u003cb\u003eYou'll need a Brighter Planet API key. See the \"API keys\" section below for details.\u003c/b\u003e\n\nFirst get the gem:\n\n    $ gem install carbon\n\nCarbon works by extending any Ruby class you're using to represent an emission source. For instance, let's say you have a Ruby class \u003ctt\u003eRentalCar\u003c/tt\u003e that represents a rental car on your lot. (Note that ActiveRecord models work great with this gem.)\n\n    class RentalCar\n      attr_accessor :model, :model_year, :fuel_economy\n      class Make\n        attr_accessor :name\n        def to_param\n          name\n        end\n      end\n      def make\n        @make ||= Make.new\n      end\n    end\n\nIn 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:\n\n    class RentalCar\n      # [...]\n      include Carbon\n      emit_as :automobile do\n        provide :make\n        provide :model\n        provide :model_year\n        provide :fuel_economy, :as =\u003e :fuel_efficiency\n      end\n    end\n\nWhen you want to calculate emissions, simply call \u003ctt\u003eRentalCar#emission_estimate\u003c/tt\u003e.\n\n    \u003e my_car = RentalCar.new([...])\n    =\u003e #\u003cRentalCar [...]\u003e\n    \u003e my_emission = my_car.emission_estimate\n    =\u003e #\u003cCarbon::EmissionEstimate [...]\u003e\n    \u003e my_emission.to_f\n    =\u003e 4919.2\n    \u003e my_emission.emission_units\n    =\u003e \"kilograms\"\n    \u003e my_emission.methodology\n    =\u003e \"http://carbon.brighterplanet.com/automobiles.html?[...]\"\n\n== API keys\n\nYou should get an API key from http://keys.brighterplanet.com and set it globally:\n\n    Carbon.key = '12903019230128310293'\n\nNow all of your queries will use that key.\n\n== Timeframes and 0.0kg results\n\nYou submit this query about a flight in 2009, but the result is 0.0 kilograms. Why?\n\n  $ carbon \n  carbon-\u003e flight\n  [...]\n  flight*\u003e date '2009-05-03'\n    =\u003e 0.0 kg CO2e\n  flight*\u003e url\n    =\u003e http://carbon.brighterplanet.com/flights.json?date=2009-05-03\n\nIt's telling you that a flight in 2009 did not result in any 2011 emissions (the default timeframe is the current year).\n\n  flight*\u003e timeframe '2009'\n    =\u003e 847.542137647608 kg CO2e\n  flight*\u003e url\n    =\u003e http://carbon.brighterplanet.com/flights.json?date=2009-05-03\u0026timeframe=2009-01-01/2010-01-01\n\nSo, 850 kilograms emitted in 2009.\n\n== Association serialization\n\nYour objects' attributes are serialized via \u003ctt\u003e#to_characteristic\u003c/tt\u003e or \u003ctt\u003e#to_param\u003c/tt\u003e (in that order of preference) before being submitted to the web service. \n\nFor example:\n\n    class RentalCar \u003c ActiveRecord::Base\n      belongs_to :automobile_make\n      emit_as :automobile do\n        provide :automobile_make, :as =\u003e :make\n      end\n    end\n    \n    class AutomobileMake \u003c ActiveRecord::Base # schema includes :name\n      has_many :rental_cars\n      alias :to_characteristic :name\n    end\n    \nWithout \u003ctt\u003eAutomobileMake#to_characteristic\u003c/tt\u003e, the library would have no way of knowing how to serialize.\n\n== Using timeouts\n\n    \u003e RentalCar.new.emission_estimate :timeout =\u003e 100\n    \nRuns a realtime request but allows timing out the network call. Raises \u003ctt\u003eTimeout::Error\u003c/tt\u003e if timeout is exceeded.\n\n== Certified calculations\n\nYou can run {certified calculations}[http://brighterplanet.com/certified] by setting \u003ctt\u003ecertified\u003c/tt\u003e to true.\n\n    \u003e RentalCar.new.emission_estimate :certified =\u003e true\n\n== Persisted queries\n\nYou can specify that the result be persisted in low-latency storage so that future identical requests can use the same estimate:\n\n    \u003e RentalCar.new.emission_estimate :guid =\u003e 'A_GLOBALLY_UNIQUE_IDENTIFIER_FOR_THIS_EMISSION_ESTIMATE'\n\n== Asynchronous queries\n\n=== Using a callback\n\nTo specify that the result of a query should be POSTed back to you, simply pass an URL as the \u003ctt\u003e:callback\u003c/tt\u003e option to \u003ctt\u003e#emission_estimate\u003c/tt\u003e:\n\n    \u003e RentalCar.new.emission_estimate :callback =\u003e 'http://example.com/my/callback/handler'\n\nA good way to test this is to set up a {PostBin}[http://postbin.org].\n\n=== Using polling\n\nBy combining \u003ctt\u003e:guid\u003c/tt\u003e and \u003ctt\u003e:defer =\u003e true\u003c/tt\u003e, you can poll for a result:\n\n    \u003e batmobile.emission_estimate :guid =\u003e '[...]', :defer =\u003e true\n    # Do other things . . . and then:\n    \u003e batmobile.emission_estimate :guid =\u003e '[...]'\n\nIf the result isn't available by the time you want it, a standard synchronous estimate will be provided.\n\n== Exceptions\n\nSince this gem connects to a web service, you need to be ready for network problems and latency. For example:\n\n    begin\n      my_emission = my_car.emission_estimate\n    rescue ::SocketError, ::EOFError, ::Timeout::Error, ::Errno::ETIMEDOUT, ::Errno::ENETUNREACH, ::Errno::ECONNRESET, ::Errno::ECONNREFUSED\n      # These are general network errors raised by Net::HTTP.\n      # Your internet connection might be down.\n    rescue ::Carbon::RateLimited\n      # In order to prevent denial-of-service attacks, our servers limit request rates.\n      # The gem will try up to three times to get an answer back from the server, waiting slightly longer each time.\n      # If you still get this exception, please contact us at staff@brighterplanet.com and we'll lift your rate.\n    rescue ::Carbon::RealtimeEstimateFailed\n      # Our server returned a 4XX or 5XX error.\n      # Please contact us at staff@brighterplanet.com.\n    rescue ::Carbon::QueueingFailed\n      # 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.\n      # Please contact us at staff@brighterplanet.com.\n    end\n    \n== Console\n\nThis library includes a special console for performing calculations interactively. Quick Start #1 provides an example session. Here is a command reference:\n\n=== Shell mode\n\n[+help+]                           Displays a list of emitter types.\n[+key+ _yourkey_]                  Set the {developer key}[http://keys.brighterplanet.com] that should be used for this session. Alternatively, put this key in \u003ctt\u003e~/.brighter_planet\u003c/tt\u003e and it will be auto-selected on console startup.\n[+_emitter_type_+]                 (e.g. +flight+) Enters emitter mode using this emitter type.\n[\u003ctt\u003e\u003ci\u003eemitter_type num\u003c/i\u003e\u003c/tt\u003e] (e.g. \u003ctt\u003eflight 0\u003c/tt\u003e) Recalls a previous emitter from this session.\n[+exit+]                           Quits.\n  \n=== Emitter mode\n\nIn Emitter mode, the prompt displays the emitter type in use. If a timeframe has been set, the timeframe is also included in the prompt.\n\n[+help+]                               Displays a list of characteristics for this emitter type.\n[\u003ctt\u003e\u003ci\u003echaracteristic value\u003c/i\u003e\u003c/tt\u003e] (e.g. \u003ctt\u003eorigin_airport 'lax'\u003c/tt\u003e) Provide a characteristic. Remember, this is Ruby we're dealing with, so strings must be quoted.\n[+timeframe+]                          Display the current timeframe in effect on the emission estimate.\n[\u003ctt\u003etimeframe \u003ci\u003etimeframe\u003c/i\u003e\u003c/tt\u003e]  (e.g. \u003ctt\u003etimeframe '2009-01-01/2010-01-01'\u003c/tt\u003e or just \u003ctt\u003etimeframe '2009'\u003c/tt\u003e) Set a timeframe on the emission estimate.\n[+emission+]                           Displays the current emission in kilograms CO2e for this emitter.\n[+lbs+, +pounds+, or +tons+]           Display the emission using different units.\n[+characteristics+]                    Lists the characteristics you have provided so far.\n[+methodology+]                        Summarizes how the calculation is being made.\n[+reports+]                            Displays intermediate calculations that were made in pursuit of the emission estimate.\n[+url+]                                Generates a methodology URL suitable for pasting into your browser for further inspection.\n[+done+]                               Saves this emitter and returns to shell mode.\n\n== Copyright\n\nCopyright (c) 2011 Brighter Planet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fcarbon-old","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaradayio%2Fcarbon-old","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fcarbon-old/lists"}