Getting Started

The Cogo Carbon Engine is distributed as a Docker image you can run locally or install on your own infrastructure. The image is hosted on the GitHub container repository. No authentication is required to pull this image.

You'll need a license key from Cogo in order to run the container. Please contact your Cogo representative to request a license key if you do not have one.

Before getting into the full documentation of the Carbon Engine API, you might want to try out the requests described below.

Notes:

Each Cogo license is configured to use a specific datapack (set of climate data).
These examples use the Cogo Demo datapack so you can follow along exactly. If your license is configured with a different datapack, then responses will be different.
These examples show the results of using a datapack that includes quantified climate actions. If your datapack does not include quantified climate actions then all action and savings related fields will be empty.
Carbon Engine exposes an HTTP server on port 80 and an HTTPS server on port 443.
The request examples use curl. If you do not have curl, you can install it here. Otherwise, you can make these requests with your preferred tool like Postman.

Pulling the Docker image from Github Container Registry

The Carbon Engine Docker image is hosted on the Github Container Registry (GHCR). To pull the latest image, you can run:

docker pull ghcr.io/consciousconsumers/carbon-engine

Visit the Carbon Engine package page on GitHub to see a list of all the versions that are available to download. The most up-to-date image intended for client use will be tagged latest. Alternately, you can pin to a specific version if you prefer. Please note, development and pre-release images will also be listed but only images tagged with a Semver number should be used.

Running the container locally

Replace the text license-here in the command below with your license key.

On your local development machine with Docker installed, run the following command. The image pulled will be the one tagged latest in the GHCR.

docker run \
  -e COGO_AUTHENTICATION_MODE=none \
  -e COGO_LICENSE="license-here" \
  -p 80:80 -p 443:443 --rm ghcr.io/consciousconsumers/carbon-engine

Get a list of categories

First of all, request the categories that are configured for your license. Each license has a different set of categories, so the examples shown below may differ from what you see.

To see all your categories, run:

% curl localhost/api/v2/categories

As an example, you will get back something that looks like:

{
  "categories": [
    ...,
    {
      "code": "14",
      "metadata": [],
      "names": ["Groceries"],
      "realised_action_codes": [],
      "unrealised_action_codes": ["diet-red-meat-free"],
      "value": "0.846728",
      "values": ["0", "0", "0.846728"]
    },
    ...
  ],
  "revision_id": 168
}

Calculate a footprint

The code for the groceries category is 14, so let's use that to make a request to footprint a $100 groceries transaction.

We're going to use the stateless /footprint endpoint, which receives transactions, calculates and returns the footprints, without storing any data.

Send the $100 grocery transaction to the stateless endpoint:

% curl -H 'Content-Type: application/json' -d '{
  "transactions": [
    {"category": "14", "amount": "100.00", "date": "2023-07-01", "id": "1"}
  ]
}' localhost/api/v2/footprint

You'll receive a response with the footprints and savings:

{
  "non_transactional_savings": [],
  "response_errors": [],
  "revision_id": 168,
  "transactions": [
    {
      "footprint": "84.67",
      "id": "1",
      "ordered_cues": [
        {
          "action_code": "diet-red-meat-free",
          "savings_type": "quantified",
          "value": "9.98"
        },
        {
          "action_code": "diet-vegan",
          "savings_type": "quantified",
          "value": "31.48"
        },
        {
          "action_code": "diet-vegetarian",
          "savings_type": "quantified",
          "value": "21.87"
        }
      ],
      "ordered_feedback": [
        {
          "action_code": "diet-red-meat-free",
          "savings_type": "missing_responses",
          "value": null
        },
        {
          "action_code": "diet-vegan",
          "savings_type": "missing_responses",
          "value": null
        },
        {
          "action_code": "diet-vegetarian",
          "savings_type": "missing_responses",
          "value": null
        }
      ],
      "raw_scoped_footprint": {
        "scope_1": "0.00",
        "scope_2": "0.00",
        "scope_3": "84.67"
      }
    }
  ]
}

You can see that the transaction was footprinted at 84.67 kilograms CO2e.

You can also see three items in ordered_cues. The Carbon Engine is suggesting actions the user can take to lower their carbon footprint - in this case, there are unrealised savings of 9.98, 31.48 and 21.87 kilograms CO2e respectively. If the user were to choose a vegan diet for example, that would reduce their footprint by 31.48 kilograms CO2e for this transaction. There are no realised savings (in ordered_feedback) because we didn't tell the Carbon Engine about this user's diet, but we can fix that by asking the user the appropriate question.

See all questions and valid responses for climate actions

To see all the questions and valid responses available in your installation, run

curl localhost/api/v2/questions

Calculate a footprint with an active climate action

Let's say we know that the user has a vegan diet. With that knowledge, we can re-submit the footprint request:

% curl -H 'Content-Type: application/json' -d '{
  "transactions": [
    {"category": "14", "amount": "100.00", "date": "2023-07-01", "id": "1"}
  ],
  "responses": {
    "diet": [{"value": "vegan"}]
  }
}' localhost/api/v2/footprint

Which now responds with quantified savings:

{
  "non_transactional_savings": [],
  "response_errors": [],
  "revision_id": 168,
  "transactions": [
    {
      "footprint": "34.57",
      "id": "1",
      "ordered_cues": [
        {
          "action_code": "diet-red-meat-free",
          "savings_type": "quantified",
          "value": "0.00"
        },
        {
          "action_code": "diet-vegan",
          "savings_type": "quantified",
          "value": "0.00"
        },
        {
          "action_code": "diet-vegetarian",
          "savings_type": "quantified",
          "value": "0.00"
        }
      ],
      "ordered_feedback": [
        {
          "action_code": "diet-red-meat-free",
          "savings_type": "quantified",
          "value": "0.00"
        },
        {
          "action_code": "diet-vegan",
          "savings_type": "quantified",
          "value": "50.10"
        },
        {
          "action_code": "diet-vegetarian",
          "savings_type": "quantified",
          "value": "0.00"
        }
      ],
      "raw_scoped_footprint": {
        "scope_1": "0.00",
        "scope_2": "0.00",
        "scope_3": "84.67"
      }
    }
  ]
}

Now that we know the user has a vegan diet, there are no further unrealised savings that can be achieved for this transaction (reported in ordered_cues); instead those savings have been realised (reported in ordered_feedback) and the footprint for this transaction has reduced to 34.57 kilograms CO2e!

Refer to the API documentation for more information about querying the API to understand the different questions you can ask your users, and how to validate the responses to those questions.