Create a climate rating system by deploying an API server and a CouchDB instance using Cloudant

While the switch to clean energy in our homes will make a real and important impact to the climate, energy usage in the commercial sector is often higher than in the domestic sector (such as our homes). A key part of this commercial energy consumption goes into making products that we buy. However, while some products we buy come with an Energy-efficiency rating, there’s nothing provided that tells us the amount and type of energy ( i.e., fossil vs renewable) used to manufacture the product in the first place. Wouldn’t it be great if we could compare the climate impact across different manufactures’ products–and perhaps include impact comparison on things outside of energy, such as water consumption. What’s really needed is a comprehensive Climate Impact Rating for products that can be presented to a consumer as some kind of labelling system. The idea is to expand existing product labelling systems, to include a comprehensive Climate Impact Rating (CIR), which will be visible at the point-of-sale (POS) by consumers (be that in-store or on-line).

Such a Climate Impact Rating could eventually include:

  • Energy Efficiency while in use (this exists today for many products)
  • Energy (and energy mix) to produce the product, potentially expressed as CO2 emissions
  • Expected lifetime of product (enabling better comparison between production energy vs in-use energy)
  • Other (non-CO2) green-house gas emissions to produce the product (e.g., from fertilizer)
  • Other consumables (e.g., water to produce the product)
  • Recyclability
  • Repairability (as part of the Right to Repair initiative)

One of the key challenges of any such labelling system is that it be, first and foremost, understandable by the intended reader–as well as comprehensive in terms of what it includes. We envision that eventually this would be printed on products (much like today’s Energy Efficiency or Food labelling). Ahead of that, however, we’d like to enable POS scanning using smart phones to translate barcodes into a visible rating.

One further beneficial item would be to include an estimate of the climate impact of the transportation of the product to POS. By definition, this could most likely not be printed on the product (since the impact at each POS might be different), but perhaps could be looked up and displayed via a smart phone (which would know the location), or online.

Creating such a labelling system is a large and global undertaking, which will require many underlying components, technologies, and agreements to come together. For the Call for Code 2020 Challenge on Energy, we are encouraging you to experiment with building out some of these components–so they can be brought together to enable this overall labelling system. These components fall into a number of categories:

Core-Architecture Use the provided starter kit to get a basic system up and running that supports Consumer APIs.
Rating Display Develop new and interesting ways of displaying the CIR (e.g., via augmented reality on a mobile device, within search engines, and on product listings.
Data Science Determine the best way to map raw data into the chosen label? Just exposing consumers to a list of numbers won’t work, since it will not be comprehensible. How can we summarize the raw data into as few factors as possible? For example, is it better to represent energy as CO2 produced (i.e., it combines amount of energy and use of renewables) or keep these separate? If the lifetime of a product is long, but its energy to create is high, is this better than a short-lived product with low energy? You could experiment with algorithms by placing them in the server side (i.e., include their output in the product info returned by the API), or you could run them on the client side. Separately, how might we also include summary data (e.g., by CO2 per country/region) ahead of having detailed information for a significant number of products?
Labelling Design Experiment (and maybe user test) and then propose a design of the label that is both comprehensive and understandable by consumers. Use the experience from food labelling and existing energy ratings as examples.
Additional Storyboards Develop additional storyboards (and interfaces) for users who are manufactures, administrators, and auditors.

For the Call for Code 2020 Challenge on Energy, we’re asking you to explore the starter kit in this tutorial to get a basic system up and running that supports Consumer APIs. Maybe you can develop a better architecture? Maybe you can add some of the components listed above?

Note: This solution starter was initially created at the United Nations Human Rights Office in Geneva, Switzerland on February 27-28, 2020, and built out over following 4 weeks. It features contributions by technologists from JPMorgan Chase, Persistent Systems, IBM, and Red Hat.

Learning objectives

This tutorial provides a solution starter that shows you how to provision a prototype Climate Impact Rating system that supports consumer APIs. The tutorial provides a basic architecture for you to experiment with building out additional climate rating components and includes:

  • A CouchDB NoSQL database layer holding both individual product ratings.
  • A basic API server that allows data to be inserted and extracted from the database. This API is expressed as an OpenAPI (Swagger) document, so you can build your own clients.
  • Deployment tools to stand up the above on the IBM Cloud, within the free-tier plan.

The database is populated with some initial example data to get you started.

Architecture diagram

  1. User scans a product barcode with an app, which then calls the Climate Impact Rating API, passing in the barcode ID.
  2. Climate Impact Rating API retrieves the ratings data that matches that barcode ID.
  3. Climate Impact Rating API returns the ratings data for the app to format and display appropriately.
  4. Manufacturers can upload product and ratings data via the Climate Impact Rating API (perhaps via a reserved portal).
  5. In the future, a Climate Impact Analyzer will run in the background to produce summary data, enabling broader ratings queries to be satisfied by the API.


You should have a basic understanding of calling APIs via HTTP. You could also learn more about using OpenAPI (Swagger). In addition, you’ll need an IBM Cloud account, with the latest IBM Cloud tools on your local machine.

Estimated time

Completing this tutorial should take about 30 minutes.


Step 1: Clone the repo

Clone the repo, so that you have a copy of the API server locally on your machine:

git clone

A directory will have been created called Solution-Starter-Kit-Energy-2020, and within that an example directory that contains the source of the API Server.

Step 2: Provision a CouchDB instance using Cloudant

Log into the IBM Cloud and provision a CouchDB instance using Cloudant. From the catalog, select Databases and the Cloudant panel:

Cloudant Instance

Once selected, you can choose your Cloudant plan – there is a free tier for simple testing that is sufficient to run this CIR example. You should choose an appropriate region, give the service a name, and it is recommended you choose Use only IAM under Available authentication methods. You can leave the other settings with their defaults. Click the blue Create button when ready.

Cloudant Instance 2

Once your Cloudant instance has been created, you need to create a service credential that the CIR API Server can use to communicate with it. By selecting your running Cloudant instance, you can choose Service credentials from the left hand menu:

Cloudant Credentials

Create a new service credential. giving it a name (it doesn’t matter what you call it):

Cloudant Credentials 2

Once created, you can display the credentials by selecting view service credentials, and then copy the credential, so you are ready to paste it into the code of the API Server in the next step:

Cloudant Credentials 2

Step 3: Prepare the API Server

To prepare the API Server, you need to paste in the service credentials you created in the step above. In the cloned directory, open the file example/ and you will see that an old credential is defined near the top of the file:

API cred before

You need to replace this with the credentials you just created, for example:

API cred after

Save the file, and your API server is ready to run!

Step 4: Run the API Server

You can run the API server either locally on your machine, or in a Docker container. The server requires python, flask, flaskrestx, so you may find it easier to run it in a container (a Docker file is provided).

Run the API Server in a Docker Container

If you have docker set up on your machine, you can build and run a docker image of the API server. Run the following commands from the example directory in your cloned repo:

docker build . -t cir-api-server
docker run -p 8080:8080 cir-api-server

The flask server in the docker container should echo something similar to the following:

 * Serving Flask app "./"
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on (Press CTRL+C to quit)

The API will then be available on

Run the API Server locally

To run the API server locally, you need to ensure all the dependencies are installed on your local machine. A Pipefile is provided to enable pipenv to install the specific dependancies – you first need to ensure you have python (3.6.x recommended) and pipenv installed. Here’s an example of doing this on MacOS:

brew install python
pip install --user pipenv
pipenv install

Now that you have the dependencies, you can run the API server itself (from within the example directory in your cloned repo)

pipenv run python ./

The flask server should echo something similar to the following:

 * Serving Flask app "server" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on (Press CTRL+C to quit)

Step 5: Test API endpoints

The first time you execute an API, the API server will create the product CIR database and upload it with a small amount of dummy data, so that you can experiment.

As mentioned above, if you are running locally the API will be published on, while if running by docker it will be published on The API Server will also render a Swagger/OpenAPI specification for the API, at this root url:

Swagger Example

Clicking on the swagger.json url at the top of the screen allows you to extract the swagger specification, for use by Swagger/OpenAPI tooling to generate a client in the language of your choice.

You can also use curl to execute simple actions (remember to substitute127.0.0.1:5000 as the url endpoint if you are running locally, in the following examples).

To retrieve a product CIR for a given barcode you can execute a GET with a query parameter (remember to substitute127.0.0.1:5000 as the url endpoint if you are running locally):

curl ""

This should return something similar to:

[{"id": "0125551234508", "barcode_id": "0125551234508", "type": "AIR CONDITIONER", "category": "SPLIT AIR-CONDITIONER", "model": "A-890AM", "brand": "Brand - A", "rating_data": {"efficiency": 4, "energy": 44.66160323, "CO2": 46.61812622, "otherGG": 61.61812622, "water": 241.0, "plastic": 1327.42056, "lifetime": 20.0, "recyclability": 9, "repairability": null}}]

To retrieve all products you can execute a simple GET:

curl ""

This should return a list of products.

You could also create a new product entry

curl -d '{"barcode_id": "1125761234500", "type": "REFRIDGERATOR", "category": "FRIDGE_FREEZER", "model": "F-13876", "brand": "Brand - F", "rating_data": {"efficiency": 4, "energy": 44.66160323, "CO2": 46.61812622, "otherGG": 61.61812622, "water": 241.0, "plastic": 1327.42056, "lifetime": 20.0, "recyclability": 9}}' -X POST "" -H "Content-Type: application/json"


This tutorial provided a solution starter that showed you how to get a basic system up and running that supports consumer APIs. The tutorial also provided a basic architecture for you to experiment with building a climate rating system.

Binu Midhun
Vincent Batts
Mark Meiklejohn
Roberto Mosqueda