maasglobal / sustainable-mobility-api

Library and API to calculate CO2 emissions for personal mobility.

Sustainable Mobility API

This project consists of a Python library and HTTP API for estimating the environmental impact of personal mobility.

Estimator

The estimator consists of a Python library to calculate CO2 emissions for a transport trip based on the distance and mode. The library has been published to the Python Package Index as transport-co2.

The README in the estimator folder also have examples on the library responses, for various modes of transportation.

API

The API provides an HTTP(s) endpoint to estimate the CO2 emissions for a transport trip. Internally, the API relies on the "transport-co2" estimator library.

Please go into api folder to read more about running locally or deploying as docker container or serverless function.

Roadmap

This project is intended as a proof-of-concept and to generate feedback for future development. See our project roadmap for upcoming plans and ideas.

Support or feedback

If you have ideas for this project or need assistance, please contact us via the project issue tracker.

sustainable-mobility-api's Issues

Fix servers selection in server and specification

@huksley asked the following in PR #20:

Any way to fix servers entry which is generated as empty now?

Task

Determine if/how to set the server value in the specification or documentation UI. Is this something that Connexion can do automatically? Can this be done in a way that is deployment agnostic?

Determine how transport CO2 estimator could be used in different programming languages

This project currently consists of a Python library. However, Python may not be in use in companies or organizations that would benefit from being able to estimate transport CO2. E.g., many companies are using Java or JavaScript for their production backends.

Initial target languages should be, in decreasing order of priority:

• Python
• JavaScript (Node.js)
• Java
• Go
• Ruby
• C#

Task

• research possibilities for defining cross-language code from a single codebase
• consider whether a generic data structure or storage format could be used instead of coding the model in a specific programming language
• document efforts and findings in this issue as comments
• create a proposal for cross-language approach, to inform the project roadmap

Write initial unit test(s) for estimation function

We need to write unit tests to lend confidence that this library is working correctly over time. The initial tests can be reasonably simple. The main goal here is to set up the process for writing unit tests in this project.

Task

• choose an appropriate method to write unit tests in Python projects (e.g., pytest)
• write initial test(s) for the estimation function
• document how to run the tests

Update HTTP API dependencies

There are updates available for the HTTP API dependencies. Make sure we are at the latest compatible versions, including any security releases.

Continue researching CO2 models for transportation carbon estimation

As part of the 0.2 release cycle, we want to perform due diligence to try and find a recent/relevant model for transportation CO2 emissions.

Task

Search multiple sources for transportation CO2 emissions model:

• peer-reviewed journals
• governmental agencies (e.g. EEA, US DOT, etc.)
• open-source software ecosystem

Document any efforts/findings in the project README.

Resources

• Approaches and Techniques for Modelling CO2 Emissions from Road Transport
• The environmental impact of today’s transport types - an example of a cross-mode carbon breakdown, although it lacks links specific sources

Consolidate Flask and Serverless code

The API currently has redundant definitions and handlers for API endpoints in the:

• Connexion-based Flask app
• Serverless-based lambda handler

These definitions are prone to go out of sync and currently require the duplicate implementation of every endpoint feature.

Task

Consolidate the Flask and Serverless app, so they use shared handler code (the Flask app).

Resources

• The Official Guide to Serverless Flask
• Serverless WSGI

Migrate from Pipenv to Poetry

We are migrating our open-source, data science tooling over to Poetry. The main reasoning is related to the maintainership of the Poetry project and that it more closely aligns with the Python PEP process.

When the opportunity arises, migrate this project from Pipenv to Poetry.

Create documentation website

It would be useful to have more information around this project than is currently provided in the README. For example, we are finding some useful resources related to transport CO2 emissions. Create a basic static site to compile the resources and documentation for this project.

Resources

• International Energy Agency energy-flow Sankey diagram showing that the majority of oil resources are fed to the Transport industry
• Our World in Data historical CO2 emissions by fuel type

Create project roadmap

We need a project roadmap for a few of reasons:

• give the project some direction
• know when we have achieved desired goals/steps
• help onboard new contributors

Let's add a roadmap, either as in the README or as a wiki document.

Add country as input parameter

Where we have data available, we could then use country specific efficiency of their car fleet, trains etc. Also for #24 we could take into account that country's CO2 emission for energy production.

Add support for all modes defined by OpenTripPlanner

OpenTripPlanner is an open-source routing and trip planning engine, that will soon have support for multi-modal journies. We would like to align with the work of OpenTripPlanner since it is in wider use within the transportation industry.

Transport modes

Our library currently supports the following transport modes:

sustainable-mobility-api/estimator/transport_co2/model.py

Lines 42 to 69 in f9b3db1

	class Mode(Enum):
	"""
	Data structure containing grams of CO2/vehicle KM for several modes of transport
	along with average occupancy for each mode.
	Source data:
	CO2 emissions from passenger transport
	from European Environment Agency
	https://www.eea.europa.eu/media/infographics/co2-emissions-from-passenger-transport/view
	"""
	def __init__(self, avg_co2_per_vehicle_km: float, avg_occupancy: float):
	self.avg_co2_per_vehicle_km = avg_co2_per_vehicle_km
	self.avg_occupancy = avg_occupancy
	LIGHT_RAIL = (2184, 156)
	SMALL_CAR = (168, 1.5)
	LARGE_CAR = (220, 1.5)
	SCOOTER = (86.4, 1.2)
	BUS = (863, 12.7)
	def estimate_co2(
	self,
	distance_in_km: float,
	*,
	co2_per_vehicle_km: Optional[float] = None,
	occupancy: Optional[float] = None,
	) -> float:

The OpenTripPlanner TraverseMode class lists the following transport modes:
https://github.com/opentripplanner/OpenTripPlanner/blob/36d7a6a38848d9307692fba78130382909d6fa96/src/main/java/org/opentripplanner/routing/core/TraverseMode.java#L11-L16

Task

Add support for all documented modes from the OpenTripPlanner library with a mapping to CO2 coefficients in our current estimator model.

Related issues

• This task is split from #15
• the upstream OTP project issue: opentripplanner/OpenTripPlanner#3076

Create mock HTTP server for serving estimates in local dev environment

As a proof-of-concept, let's use the API specification to auto-generate an HTTP scaffold and then wire up the estimation library inside of the endpoint function(s).

Resources

• Connexion could be a good basis for connecting the API specification to endpoint function(s)

Make CO2 calculations based on liters

The API calculates CO2 emission based on mileage per mode of transport and people travelling, which is super useful! However, some platforms (e.g. tank cards) don't have mileage/distance/location information, only how many liters of a certain fuel are tanked.

Maybe this API could also calculate CO2 emission based on the amount and type of fuel tanked. Data on how much CO2 is emitted per fuel type can be found on https://www.co2emissiefactoren.nl/lijst-emissiefactoren/

p.s.
I don't have any knowledge on coding, so not sure if this is possible to implement, just someone who is passionate about MaaS.

Addendum

This section was added after the initial issue was created, in order to add information and resources related to the task.

Resources

• Ecoscore - describes a method of calculating CO2 emissions per litre of petrol and diesel
• table of CO2 emissions by fuel without mention of source or methodology (may still prove useful)
• Natural Resources Canada published a fact sheet estimating CO2 kg/L for several fuels - namely petrol, diesel, biodiesel, and ethanol
• IPCC emissions factors database has extensive data on road transportation fuel combustion activities
• U.S. Environmental Protection Agency published CO2 emissions metrics for gasoline and diesel combustion as well as a greenhouse gas equivalencies calculator

Research + implementation of regional layers of CO2 calculation

Do research, check the feasibility and implement regional layers to calculate the emissions on a global, continental or countrywide level.

Add simple sustainable labeling to CO2 estimates

The raw CO2 estimates can be somewhat ambiguous to end-users. Without causing too much controversy, let's see if we can add a summarizing label to the CO2 estimates, such as "low", "medium", or "high".

Note: this was proposed during the MaaS Alliance demo for the current state of this project.

Consider if/how to incorporate power generation CO2 emissions used for electric vehicles

Electric vehicles may not produce emissions during transit. Instead, generating power for electric vehicles produces emissions. Determine if/how to account for energy generation costs of electric vehicles such as electric cars, scooters, and bikes.

Add support for compression (e.g. gzip)

With recent changes, we are looking at allowing requests to be made with a considerable amount of data (namely lists of itinerary objects with arbitrary fields.) One performance optimization for large payloads is to use gzip, or similar, compression.

Task

• determine how to define that the API supports compression
• add necessary changes to specification and in code to support compression

Resources

• discussion about defining compression in OpenAPI Specification
• GZIP compression might be best added at the HTTP server level
• AWS Enabling payload compression for an API

Create Helm chart for deploying CO2 estimation endpoint(s)

Companies using Kubernetes might prefer to deploy the CO2 estimation endpoints on their infrastructure. We can make this easy by providing a Helm chart (or whatever is standard) that deploys the function behind one or more HTTP endpoints, conforming to the specification.

Allow developers to override model parameters

Our library currently uses hard-coded formulas to calculate CO2 emissions based on vehicle averages. Some transport providers may have specific data on the CO2 emissions per passenger kilometer for their fleet. So, they would get more accurate estimations if they could tweak the parameter values when estimating CO2.

Task

• developers can override all parameters used in CO2 calculation
• parameters have sensible defaults
• defaults are based on an existing CO2 emissions model
• project documentation includes reference to the underlying CO2 model used for defaults

[API] Consider whether to use GeoJSON for origin/destination locations

We are currently handling API requests that provide an itinerary origin and destination containing latitude/longitude pairs (in WGS84 decimal degrees).

Our current design is tending towards using explicit latitude and longitude properties on a coordinate schema, to avoid ambiguity of the X/Y or Y/X coordinate systems.

GeoJSON defines a, somewhat ambiguous but increasingly adopted, schema in the following form:

  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1]
  },
  "properties": {
    "name": "Dinagat Islands"
  }
}

Task

• determine whether to use GeoJSON for the allowed data structure of origin and destination data
• if desired, add support for GeoJSON definitions (e.g. by adding an itinerary_option_origin_destination_geojson schema

Resources

The GeoJSON RFC defines the coordinates as follows:

A position is an array of numbers. There MUST be two or more elements. The first two elements are longitude and latitude, or easting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element.

https://tools.ietf.org/html/rfc7946#section-3.1.1

Time based distance estimation

In cases where a transit provider only provides time spent on a particular leg (e.g., "ride the bus for 10 minutes"), we could use an average speed for that mode to calculate the distance and hence provide a CO2 estimate.

The main task here would be to gather (good) average speed estimates for all modes. Alternatively users can provide their own average speed.

Create CloudFormation template to deploy estimation function on AWS via an HTTP endpoint

Companies using AWS might prefer to deploy the CO2 estimation endpoints on their infrastructure. We can make this easy by providing a CloudFormation template that deploys the function behind one or more HTTP endpoints, conforming to the specification.

Determine if/how to factor weather conditions into CO2 estimation

The weather may play a factor in vehicle emissions or efficiency, such as by affecting the efficiency of electric vehicle batteries. Determine if/how we might include a weather component in the CO2 estimation model.

Initial prototype with documentation

This issue signifies the initial prototype work for the Transport CO2 library, as part of the initial work on the project roadmap. The deliverables so far have been:

• initial research for CO2 models
• initial research for competing or similar libraries
• prototype library
• initial documentation
• first round of user feedback

We will continue building the project roadmap based on user feedback.

Consider if/how to incorporate vehicle speed into CO2 estimates

Vehicle speed (and terrain) plays an essential role in accurately estimating vehicular CO2 emissions. Determine if/how we should allow vehicle speed, location (urban or suburban), and terrain to factor into CO2 estimates.

HTTP API should support estimation for multiple multi-leg itineraries via a single request

In some cases, it would be convenient for a mobility operator to receive CO2 estimates for multi-leg itineraries via a single API request. The response could return estimations for each leg and/or a single estimation for the entire itinerary as a whole.

Determine if/how to support the extension modes (GTFS) and NeTEx submodes

We want to align the project with OpenTripPlanner (OTP) and support carbon estimation for common transport modes. OTP developers are in discernment about how to align with GTFS and NeTEx standards.

Task

Research and determine the feasibility of estimating CO2 emissions of GTFS and NeTEx transport modes. If it seems feasible, create a follow-up task to track the implementation.

Related resources

• Stemming from #47
• Based on comment opentripplanner/OpenTripPlanner#3076 (comment)

Calling docker setup with invalid parameters returns 200 OK return

curl --verbose http://localhost:8080/estimate-co2?transport_mode=small_car

< HTTP/1.0 200 OK
< Content-Type: application/json
"Not enough information was provided to calculate CO2 estimate."

Also I would return { "error": "msg" } payload in this situation.

Consider using API-first design approach

It might be useful to start with an HTTP API design for this project, i.e., showing how networked services would use the CO2 estimator. If we use the OpenAPI Specification to design/document the API, then we can use tools to auto-generate language bindings and backend server scaffolding in various programming languages.

Task

• create initial HTTP API specification for Transport CO2 estimator