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
- Use POST for CM1 queries. GET will also work (primarily for testing), but this may be deprecated.
- 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.
- Choose an impact model that corresponds to your desired calculation. Models are specificed in plural snake case (e.g. flights, automobile_trips).
- 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:
- 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.
- 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.
- By default, CM1 will perform calculations in real time and return the result as an HTTP response to the initial request.
- 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).
- 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.)
- A prose statement from DNV that describes this model's certification.
- Characteristics provided in the initial request, as interpreted by CM1.
- A list of protocols that this calculation complies with, probably in response to a comply parameter provided with the request.
- 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.
- The impact model used to perform this calculation.
- Provides handy conversions of the "carbon" decision's value to human-understandable units. See co2_equivalents for details.
- A list of errors (in prose) associated with this calculation.
- The URL to a comprehensive human-readable methodology document, constructed especially for this calculation.
- A prose statement describing the technical scope of this calculation.
- 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
Email us or join us in #brighterplanet on Freenode.