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
- Configuration
- Deployment
- Project structure
- Contribution guidelines
- Stack
- Seeder
- License
- Co2 Data
-
Clone this repository:
git clone git@github.com: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.
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:
- Use Apollo Stuido sandbox. Open your browser to https://studio.apollographql.com/sandbox/explorer
- Use GraphQL playground. Open your browser to http://localhost:4200/
- Use Postman by importing the Open API documentation
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
An example docker-compose file is available to seed the database with input CO2 data and deploy locally the API for development purpose.
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 livingseeder
is compose of modules to process the data source and populate the database
- 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
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.
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.
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.
Data(base) is licensed under the Open Database License Source code is licensed under the MIT License.
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:
- Update the excel file seeder/data/input/Open CO2.xlsx
- Update the list of first level categories in seeder/seed.js if needed
- Run the seeder cd server/seeder and npm run start
- Drop the current mongo table docker compose down -v
- Rebuild and repopulate data docker compose up -d