CM1 Documentation

• Documentation
• Pricing
• Models
• CM1

Get an API key

Get an API key ▶

All requests must include an API key. We recommend that you use a separate API key for each CM1-powered application. When creating a key, you will choose between non-commercial (free) and commercial (paid) use.

Construct a URL

Verb

Use POST for CM1 queries. GET will also work (primarily for testing), but this may be deprecated.

Host

Most queries will use impact.brighterplanet.com. For certified queries, use certified.impact.brighterplanet.com and specify compliance (see below)—but note that Brighter Planet staff must provide you with a special API key before certified calculations can be made; contact us for details.

Model

Choose an impact model that corresponds to your desired calculation. Models are specificed in plural snake case (e.g. flights, automobile_trips).

Extension

Specify your desired response format. Available machine-readable formats include xml and json. Use the js format for JSONP-driven client-side requests (see "Making client-side requests" below for details). The html format—the default—returns a human-readable methodology document.

Build your request

Submit your request to the URL you just constructed, as form-encoded data, JSON, or XML. All input is optional. Recognized input elements include:

Characteristics

Each impact model can be described using a set of characteristics. To see the characteristics available for your model, visit its model page. If no characteristics are specified, CM1 will assume an average instance of this model.

Timeframe

To restrict the calculation to a specific timeframe, specify it using ISO 8601's interval provision, method 1. By default, timeframe is assumed to be the current calendar year. Note that if the impact activity occurs outside the specified timeframe, CM1 will return 0 (zero) impact.

Timing

By default, CM1 will perform calculations in real time and return the result as an HTTP response to the initial request.

Compliance

Upon request, CM1 will constrain its calculation methodology to comply with one or more protocols. To specify compliance, use the comply parameter and set it to one or more of Greenhouse Gas Protocol Scope 1 (ghg_protocol_scope_1), Greenhouse Gas Protocol Scope 3 (ghg_protocol_scope_3), ISO 14064-1 (iso), and The Climate Registry (tcr).

Locations

For the AutomobileTrip, Shipment, and RailTrip models, origin and destination locations must be formatted as [street,]city[,state] (street always optional, state only for the United States) or, even better, [street,]postcode (street optional, city and state should not be sent). Street must start with house/building number. Be sure to specify country as a separate characteristic!

API Key

Your Brighter Planet API key, as obtained in step one, above.

Unrecognized input and invalid values for recognized characteristics will be ignored during calculation. When in doubt, submit what you can and inspect the response for interpretation.

Interpret the response

Depending on the response format specified in your URL (above), the CM1 will respond in JSON (illustrated here) or XML. (Recall that the default response format—HTML—will always return a human-readable methodology document. The specification below is for the machine-readable response formats.)

Certification

A prose statement from DNV that describes this model's certification.

Characteristics

Characteristics provided in the initial request, as interpreted by CM1.

Compliance

A list of protocols that this calculation complies with, probably in response to a comply parameter provided with the request.

Decisions

Final and intermediate conclusions drawn during the performance of this calculation. For every key, a value, unit specification, and brief description of methodology is provided. For more detailed methodology, either review the methodology URL provided with the response (below) or inspect the relevant source code.

Emitter

The impact model used to perform this calculation.

Equivalents

Provides handy conversions of the "carbon" decision's value to human-understandable units. See co2_equivalents for details.

Errors

A list of errors (in prose) associated with this calculation.

Methodology

The URL to a comprehensive human-readable methodology document, constructed especially for this calculation.

Scope

A prose statement describing the technical scope of this calculation.

Timeframe

The timeframe constraint on this calculation, as provided in the request or having defaulted to the current year.

Add the CM1 badge to your application

Developers add the CM1 badge to their applications so that users know your carbon calculations are accurate, reliable, and transparently computed. To use it, insert the following HTML wherever you want the badge to appear. For positioning, style .brighter_planet_cm1_badge

<script type="text/javascript" src="http://impact.brighterplanet.com/badge.js"></script>

Get support

In addition to the usual ways of contacting Brighter Planet, developers are invited to join us in #brighterplanet on Freenode.

Additional topics

  document.observe('dom:loaded', function() {
      new Ajax.Request('http://impact.brighterplanet.com/automobiles.json', {
          onSuccess: function(response) {
            alert(response.decisions.carbon.object.value);
          }
      });
  })
  

  <script type="text/javascript">
    function impact(response) {
      alert(response.decisions.carbon.object.value);
    }
  </script>
  <script type="text/javascript" src="http://impact.brighterplanet.com/automobiles.js"></script>
  

$ gem install carbon

<script type="text/javascript" src="/javascripts/CM1.js"></script>

$ npm install CM1

• t
• F
• r
• G