Carbon comparison

Express a carbon quantity in everyday terms, such as years of car use or a number of Google searches.

Compares a carbon quantity to things people know, such as cars, light bulbs or kettles. Use it to make an emissions figure tangible, for example next to the footprint on a booking confirmation.

Request

POST /v2/carbon-comparison

carbon_quantityintegerrequired

The carbon quantity to compare. A whole number of at least 1.

carbon_unitstringrequired

Unit of carbon_quantity: tonne, kilogram or gram.

itemsarrayrequired

One or more comparisons, each with a metric and an optional comparison_unit. Without a comparison_unit, SQUAKE picks the best match for the quantity you send.

See every field of POST /v2/carbon-comparison in the API reference

carbon_quantity takes whole numbers only. To compare 142.6 kilograms, send 142600 with the unit gram.

This request compares one tonne to the yearly use of a car, to Google searches, and to a distance whose comparison unit SQUAKE picks:

{
  "carbon_quantity": 1,
  "carbon_unit": "tonne",
  "items": [
    { "metric": "annual_usage", "comparison_unit": "cars" },
    { "metric": "per_use", "comparison_unit": "google_search" },
    { "metric": "distance_in_km_traveled" }
  ]
}

Save it as comparison.json and send it:

curl --request POST "https://api.sandbox.squake.earth/v2/carbon-comparison" \
  --header "Authorization: Bearer $SQUAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data @comparison.json

Response

The amounts in this example are illustrative. Send the request to get SQUAKE's values.

200 OKapplication/json
{
  "carbon_quantity": 1,
  "carbon_unit": "tonne",
  "items": [
    { "comparison_unit": "cars", "metric": "annual_usage", "amount": 0.5 },
    { "comparison_unit": "google_search", "metric": "per_use", "amount": 5000000.0 },
    { "comparison_unit": "by_petrol_car", "metric": "distance_in_km_traveled", "amount": 5900.0 }
  ]
}

Each item returns the metric, the comparison_unit (the one you sent, or the one SQUAKE picked) and the amount. The amount is expressed in the unit of the metric. For annual_usage, 0.5 means half a year of use. For distance_in_km_traveled, the amount is a distance in kilometers.

Metrics and comparison units

Each comparison unit belongs to one metric:

metriccomparison_unit values
amount_compensatedaverage_tree, whale
amount_producedplastic_straws
annual_consumptioncoffee_to_go, food, water
annual_usagecars, central_heating_systems, dishwashers, electric_hobs, electric_ovens, electric_tumble_dryers, fridges, gas_hobs, gas_ovens, kettles, light_bulbs, low_energy_light_bulbs, microwave_ovens, stationary_computers, washing_machines
carbon_capturedcookstove_usage
distance_in_km_per_passengerby_bus, by_coach, by_eurostar, by_ferry, by_national_rail, by_tram
distance_in_km_traveledby_diesel_car, by_electric_car, by_motorcycle, by_petrol_car, by_taxi
hourly_usagestreaming, videoconferencing
number_of_dayscruise
number_of_travelsamsterdam_to_paris_by_car, amsterdam_to_rome_by_plane, frankfurt_to_new_york_by_plane, london_to_berlin_by_train, london_to_china_by_bus, turkey_to_south_korea_by_electric_car
per_usebar_of_chocolate, cheeseburger, dyson_airblade_hand_dryer, electric_hand_dryer, email, google_search, lightweight_plastic_bag, paper_towel, pint_of_tap_water, spam_email, supermarket_plastic_bag, text_message

Errors

StatusMeaning
400The request is invalid, for example because carbon_quantity isn't a whole number of at least 1.

On this page

POST/v2/carbon-comparison

Run this request against the sandbox with your test key.

Open in API reference