MediaComem / open-co2

Open Data Database and API for CO2 Equivalent Values

An open Data Database and API for CO₂ Equivalent Values.

This Database for CO₂ Equivalent Values is made available under the Open Database License: http://opendatacommons.org/licenses/odbl/1.0/. Any rights in individual contents of the database are licensed under the Database Contents License: http://opendatacommons.org/licenses/dbcl/1.0/

Open CO2 project enables companies to estimate their CO2 footprint through an open DB and API which can be used with their accounting tool. Although most of the data are independent of the location, the database is targeted to be used by companies operating in Switzerland. In particular energy information are based on swiss electricity providers and swiss energy mix, public transports on swiss public transport providers.

Project reference on Aramis DB

Project funded by Innosuisse.

---

• First-time setup
• Test the API
  • GraphQL API (Recommended)
  • REST API
• Configuration
• Deployment
• Project structure
• Contribution guidelines
• Stack
• Seeder
  • API
  • Development
• License
• Co2 Data

---

First-time setup

• Clone this repository: git clone [e-mail]:MediaComem/open-co2.git

• Configure config files in /server/app/config, /server/seeder/config (see Configuration section for more details)

• Move to server directory: cd open-co2/server

• Run stack using docker-compose: docker-compose up --build -d

See Co2 Data in case you want to update the input data.

Test the API

The GraphQl documentation is available directly through the GraphQL endpoint and the schema can be browsed using any GraphQL client. The Open API documentation for the REST API is available and can be visualised using Swagger editor

You have 2 main options to consume the API:

GraphQL API (Recommended)

• Use Apollo Stuido sandbox. Open your browser to https://studio.apollographql.com/sandbox/explorer
• Use GraphQL playground. Open your browser to http://localhost:4200/

REST API

• Use Postman by importing the Open API documentation

Configuration

Project use Node-config to loads environment variables.

Default configuration is store in default.json JSON file in those different directories:

• /server/app
• /server/seeder

Create similar local.json files if you need specific local configuration.

To secure your production configuration, you can follow instructions at Node-config - Securing Production Config Files

Deployment

An example docker-compose file is available to seed the database with input CO2 data and deploy locally the API for development purpose.

---

Project structure

Source code is mostly located in server. The client-examples directory only provides some applications to consume the API as examples.

The server directory is splitted in two main parts:

• app is where the Express/GraphQL core server is living
• seeder is compose of modules to process the data source and populate the database

Contribution guidelines

• Use Conventional Commits guidelines for your commits
• Run npm run release to update software version and generate changelog from commits
• To contribute to adding or updating data, the tabular source file must follow some simple rules:
  • Respect a tree structure with a dedicated line for each branch
  • The root entry (Level 1) in each sheets must be unique

---

Stack

Seeder

The seeder script takes care of parsing the different categories and values to:

• generate the data graph (list of parent and children categories).
• compute average values and statistics from children categories.

Most business data logic is contained inside this step and the test coverage of this script should be extended if modified.

The seeder is a NodeJS script that populates a MongoDB database with CO2 data from an excel input file.

API

The API is a simple interface on top of MongoDB documents. Almost no logic is performed by the API.

The Co2 data are stored in a mongoDB database. The API run on a NodeJS server based on expressJS. The API is primarily defined as a GraphQL API. The GraphQL API is served thanks to Apollo GraphQL middleware that creates the routes from the GraphQL schema. The Sofa API library is used to generate automatically the REST Open API documentation and server the API as REST based on the GraphQL schema.

Development

In development you can use docker and the docker-compose provided to try the API. Jest is used as the test framework for unit tests.

License

Data(base) is licensed under the Open Database License Source code is licensed under the MIT License.

Co2 Data

See Method. Please be aware that due to some assumptions and limitations, the data may not be suitable for decision making depending on your use case.

In case you update the input data, do not forget to:

1. Update the excel file seeder/data/input/Open CO2.xlsx
2. Update the list of first level categories in seeder/seed.js if needed
3. Run the seeder cd server/seeder and npm run start
4. Drop the current mongo table docker compose down -v
5. Rebuild and repopulate data docker compose up -d