{"id":24698561,"url":"https://github.com/faradayio/carbon","last_synced_at":"2025-10-09T06:30:53.082Z","repository":{"id":2683502,"uuid":"3675996","full_name":"faradayio/carbon","owner":"faradayio","description":"Brighter Planet CM1 client for Ruby","archived":false,"fork":false,"pushed_at":"2012-09-06T23:12:53.000Z","size":278,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-19T00:21:45.957Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rdoc.info/github/brighterplanet/carbon","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faradayio.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-03-09T23:44:27.000Z","updated_at":"2024-05-16T15:49:43.000Z","dependencies_parsed_at":"2022-08-20T16:00:49.554Z","dependency_job_id":null,"html_url":"https://github.com/faradayio/carbon","commit_stats":null,"previous_names":["brighterplanet/carbon"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/faradayio/carbon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faradayio","download_url":"https://codeload.github.com/faradayio/carbon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fcarbon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000825,"owners_count":26082950,"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-10-09T02:00:07.460Z","response_time":59,"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:19.939Z","updated_at":"2025-10-09T06:30:52.753Z","avatar_url":"https://github.com/faradayio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carbon\n\nCarbon is a Ruby API client and command-line console for the [Brighter Planet impact estimate web service](http://impact.brighterplanet.com), which is located at http://impact.brighterplanet.com. By querying the web service, it can estimate the carbon emissions, energy usage, and other environmental impacts of many real-life objects, such as cars and houses, based on particular characteristics that they may have.\n\nFull documentation: [RDoc](http://rdoc.info/projects/brighterplanet/carbon) \n\n[![Build Status](https://secure.travis-ci.org/brighterplanet/carbon.png)](http://travis-ci.org/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://impact.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\nCarbon works by extending any Ruby class to be an emission source. You `include Carbon` and then use the `emit_as` DSL...\n\n    # see Carbon::ClassMethods#emit_as for more details\n    class MyFlight\n      def airline\n        # ... =\u003e MyAirline(:name, :icao_code, ...)\n      end\n      def aircraft\n        # ... =\u003e MyAircraft(:name, :icao_code, ...)\n      end\n      def origin\n        # ... =\u003e String\n      end\n      def destination\n        # ... =\u003e String\n      end\n      def segments_per_trip\n        # ... =\u003e Integer\n      end\n      def trips\n        # ... =\u003e Integer\n      end\n      include Carbon\n      emit_as 'Flight' do\n        provide :segments_per_trip\n        provide :trips\n        provide :origin, :as =\u003e :origin_airport, :key =\u003e :iata_code\n        provide :destination, :as =\u003e :destination_airport, :key =\u003e :iata_code\n        provide(:airline, :key =\u003e :iata_code) { |f| f.airline.try(:iata_code) }\n        provide(:aircraft, :key =\u003e :icao_code) { { |f| f.aircraft.try(:icao_code) }\n      end\n    end\n\nSee [RDoc on `Carbon::ClassMethods#emit_as`](http://rdoc.info/github/brighterplanet/carbon/Carbon/ClassMethods#emit_as-instance_method) for all the details.\n\nThe final URL will be something like\n\n    http://impact.brighterplanet.com/flights.json?segments_per_trip=1\u0026trips=1\u0026origin_airport[iata_code]=MSN\u0026destination_airport[iata_code]=ORD\u0026airline[iata_code]=UA\u0026aircraft[icao_code]=B737\n\nWhen you want to calculate impacts, simply call `MyFlight#impact`.\n\n    ?\u003e my_flight = MyFlight.new([...])\n    =\u003e #\u003cMyFlight [...]\u003e\n    ?\u003e my_impact = my_flight.impact(:timeframe =\u003e Timeframe.new(:year =\u003e 2009))\n    =\u003e #\u003cHashie::Mash [...]\u003e\n    ?\u003e my_impact.decisions.carbon.object.value\n    =\u003e 1014.92\n    ?\u003e my_impact.decisions.carbon.object.units\n    =\u003e \"kilograms\"\n    ?\u003e my_impact.methodology\n    =\u003e \"http://impact.brighterplanet.com/flights?[...]\"\n\nSee [RDoc on `Carbon#impact`](http://rdoc.info/github/brighterplanet/carbon/Carbon#impact-instance_method) for all the details.\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## Gotcha: 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://impact.brighterplanet.com/flights?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://impact.brighterplanet.com/flights?date=2009-05-03\u0026timeframe=2009-01-01/2010-01-01\n\nSo, 850 kilograms emitted in 2009.\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`\n:  Displays a list of emitter types.\n\n`key` _yourkey_\n:  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.\n\n_emitter_\n:  (e.g. `flight`) Enters emitter mode using this emitter type.\n\n_emitter num_\n:  (e.g. `flight 0`) Recalls a previous emitter from this session.\n\n`exit`\n:  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`\n:  Displays a list of characteristics for this emitter type.\n\n_characteristic value_\n:  (e.g. `origin_airport 'lax'`)\n:  Provide a characteristic. Remember, this is Ruby we're dealing with, so strings must be quoted.\n\n`timeframe`\n:  Display the current timeframe in effect on the emission estimate.\n\n`timeframe` _timeframe_\n:  (e.g. `timeframe '2009-01-01/2010-01-01'` or just `timeframe '2009'`) Set a timeframe on the emission estimate.\n\n`emission`\n:  Displays the current emission in kilograms CO2e for this emitter.\n\n`lbs`, `pounds`, or `tons`\n:  Display the emission using different units.\n\n`characteristics`\n:  Lists the characteristics you have provided so far.\n\n`methodology`\n:  Summarizes how the calculation is being made.\n\n`reports`\n:  Displays intermediate calculations that were made in pursuit of the emission estimate.\n\n`url`\n:  Generates a methodology URL suitable for pasting into your browser for further inspection.\n\n`done`\n:  Saves this emitter and returns to shell mode.\n\n## Copyright\n\nCopyright (c) 2012 Brighter Planet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fcarbon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaradayio%2Fcarbon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fcarbon/lists"}