(1) Overview

Introduction

During urban trips, pedestrians and cyclists are exposed to the harms and benefits of the urban travel environment, such as traffic noise, air pollution, and greenery. As environmental conditions vary geographically in urban spaces, route choice becomes an important factor in determining environmental exposure during active travel [, ]. In comparison to taking the shortest or fastest routes, environmentally sensitive route planning is likely to reduce harmful exposures from travel and increase health benefits [, , , ].

Transport, environmental, and public health research has witnessed an emergence of exposure-optimised routing studies during the last decade []. The research field supports spatial and transport planning in creating sustainable and healthy urban space and travel options [, ]. It also helps to advance conventional route planners that have mostly focused on minimising time, distance, or the monetary cost of travel []. Informed decision-making among end-users is supported by enabling access to environmental information about possible routes. Namely, pre-trip information about route qualities affects route choice if travellers perceive that the information is useful for their welfare [, ].

Most routing studies on exposure optimisation have focused on finding low-exposure routes in respect to air pollution [e.g., , , , , , ]. Other studies that optimise routes also consider traffic noise levels or the presence of greenery [, , , , ], allergens [], or extreme environmental conditions [, ]. Several groups of researchers have developed new routing algorithms or prototype route planners for finding exposure-optimised routes [, , , ].

Despite these efforts, real-world evidence on functional route planners that find exposure-optimised routes for active travel is limited. The few examples involve Clean Air Route Finder that provides multiple choices for walking and cycling routes in London. The tool provides information about trip length, travel time, and the relative decrease in air pollution in comparison to the shortest route []. An open-source mobile application called hRouting, The Health-Optimal Route Planner, enables routes in Zürich with lower exposure to ultrafine particles to be found []. Some previous route planners in Canadian cities offered cyclists the opportunity to choose a route with better air quality [, , ]. Another temporarily available routing tool, a Clean Air Route Planner, was introduced in Helsinki, where walking routes were optimised according to precise air quality information []. In Amsterdam, the Healthy Urban Route Planner (HURP) project developed a route planner for cyclists and pedestrians to reduce exposure to air pollution. A Healthy Places routing app is soon to be launched with the aim to minimize air pollution exposure during walking.

To advance the research field with open-source tools, we developed a prototype Green Paths route planning software for active travel. It enables evaluation of environmental exposure during walking and cycling, study access to healthy travel routes, and empower citizens in making health-benefitting route decisions. The open-source routing software demonstrates how least cost path routing can be made sensitive to three environmental variables—traffic noise, air quality, and street-level greenery—in an urban context. It optimises either walking or cycling routes by combining data about environmental conditions with travel time. The Green Paths software provides multiple route suggestions between externally defined origin and destination pairs, from the fastest route to the ones with less noise and air pollution or more green views. The routing results are provided via a RESTful Application Programming Interface (API) to be used either in research or for end-user routing tools and other applications. The routing software has been developed to run in the Helsinki Metropolitan Area. For other urban areas, custom data acquisition and processing steps would be needed prior to running the application. The technical documentation of the software, which is packaged within the sourced code repository and thus available both on GitHub and via the DOI (see the Availability section), includes more detailed requirements and further guidance for preparing the environmental data for other areas.

The Green Paths routing software shares some similarities with the previously developed Clean Air Route Planner for Helsinki []. Both applications use similar external data about air quality [, ] and facilitate exposure-optimised routing for walking. However, there are significant differences in terms of the scope, functionality, and applicability of the Green Paths software. For example, both walking and cycling are available as travel modes and the routing functionality is based on an original environmental impedance function. The latter combines travel time, environmental cost, and sensitivity coefficients, and provides multiple routing cost alternatives with different trade-offs between exposure benefits and travel time costs as a result. The concept and technical implementation of the environmental impedance function is explained in detail in the Implementation and architecture section of this paper.

The aim of this paper is to describe the methodology and applicability of the Green Paths routing software. The paper provides a comprehensive view of the software, including its key features and technical architecture, and complements the complete technical documentation of the software available from GitHub (included in the source code repository). The paper does not cover the user interface of the Green Paths routing tool. The paper is organized as follows: the Implementation and architecture section describes the technical context, architecture, external data, packages, and workflow of the software. The Quality control section describes the tests of routing functionality. The Availability section describes the system requirements to run the software, contributors, and software availability. The Reuse potential section describes the current application of the software in the Helsinki Metropolitan Area and replicability potential to other regions.

Implementation and architecture

Technical context

The Green Paths software is a prototype for exposure-optimised routing engines. It is an open-source software written in the Python programming language. Python provided a suitable technical base for fast prototyping of different routing features and utilising several third-party libraries. The Green Paths software has been built as prototype for demonstrating path finding equipped with rich exposure metrics between selected origin-destination pairs. Thus, it has not been optimised to provide a routing service for extensive production use.

The complete technical documentation of the software has been published along with the source code and can be accessed via its primary README.md file. The technical documentation includes a straightforward installation guide for the software as well as other supporting technical information, such as sample graph data for testing and developing the software.

Table 1 lists the third-party Python libraries that the Green Paths software depends on, excluding the sub-dependencies of the libraries. In addition, the Green Paths software requires the use of the OpenTripPlanner (OTP) open-source routing software for pre-processing OpenStreetMap-based street network data. For further information, see the Graph build package section in this paper.

Table 1

The list of third-party Python libraries used in the Green Paths routing software.


PACKAGELINKVERSION (TESTED)DESCRIPTION AND USE

Flaskhttps://github.com/igraph/python-igraph1.1.2A simple web framework for publishing the routing functionality via APIs

GeoPandashttps://github.com/geopandas/geopandas0.8.3Data structures for spatial data processing and integration

Gunicornhttps://github.com/benoitc/gunicorn20.0.4A Python WSGI HTTP Server for UNIX, used for running the APIs of the routing application as a web service

igraph (python-igraph)https://github.com/igraph/python-igraph0.8.3Graph data structure and built-in algorithms for solving least cost path problems

Shapelyhttps://github.com/Toblerity/Shapely1.7.1Geometry objects and overlay analysis

Features and software architecture

The Green Paths software has three main features: (i) scripts and utilities for combining environmental data on noise, air quality, and greenery with OpenStreetMap-based street network graph; (ii) the main routing application for finding fastest and exposure-optimised routes for both walking and cycling; and (iii) RESTful API for publishing the environmentally sensitive routing functionalities as a web service. The architecture of the software, data processing flow, and the two use cases of the Green Paths routing software are illustrated in Figure 1.

Figure 1 

The architecture, data processing workflow, and use cases of the Green Paths routing software.

The software consists of four main packages that are described in more detail in the sections below:

  1. graph_build: scripts and utilities for handling street network graph and environmental data;
  2. aqi_updater: utilities for fetching, processing, and sampling either real-time or static air quality index data for the main routing application;
  3. gp_server: the main routing application that handles routing requests;
  4. common (omitted from the Figure 1): general utilities for handling geometry data and reading and writing street network graph data in the GraphML format (I/O).

External data

The Green Paths software uses external open-access data of street network, traffic noise, air quality as Air Quality Index (AQI), and street-level greenery as Green View Index (GVI) that are described in the Table 2.

Table 2

External data currently used in the Green Paths routing software for exposure-optimised routing.


DATACONTENTMEASUREVALUE RANGEFORMATSPATIAL EXTENTSOURCE AND REFERENCES

Street network dataStreet and path networkn/an/aStandard compressed Protocolbuffer Binary Format (PBF)GlobalOpenStreetMap, www.openstreetmap.org, CC BY 2.0

Traffic noise dataDay, evening, and night A-weighted equivalent continuous sound pressure level (Lden) from road and rail traffic. Modelled every five years according to the EU Environmental Noise Directive 2002/49/EC.dB(A)40…75+Vector, shapefileEuropean urban areas[], accessible from ckan.ymparisto.fi/dataset/%7B0A7C0CF8-7BAA-49FF-835A-0B97DA89B9D4%7D, CC BY 4.0

Real-time air quality dataHourly composite air quality index covering NO2, SO2, O3, PM2.5, PM10, BC, and LDSAAir Quality Index (AQI) 2.01…5 (good…very poor)Raster, mesh size 13 × 13m, netCDFHelsinki Metropolitan RegionFMI-ENFUSER 2.0 model, [, ], accessible from the Finnish Meteorological Institute (FMI)

Static air quality dataAnnual average composite air quality index covering NO2, SO2, O3, PM2.5 and PM10 Air Quality Index (AQI) 1.01…5 (good…very poor)Raster, mesh size 13 × 13m, netCDF or TIFFHelsinki Metropolitan RegionFMI-ENFUSER 1.0 model, [], accessible from the Helsinki Region Environmental Services Authority (HSY)

Greenery dataProportion of green vegetation visible at street level based on street view panoramas and regional land cover dataGreen View Index (GVI)0…1Vector, shapefileHelsinki Metropolitan Region[], CC BY 4.0; hri.fi/data/fi/dataset/paakaupunkiseudun-maanpeiteaineisto, CC BY 4.0

Graph build package

The routing in the Green Paths software is based on a street network graph, which consists of nodes and edges between the nodes (representing street segments). Each edge is equipped with attributes about the geometry and distance of the edge, allowed travel modes, a biking safety factor, and environmental data. The nodes are characterised by only the geometry value. The required attributes and their value types are listed in the technical documentation of the software (see the Availability section below).

As illustrated in Figure 1, raw OpenStreetMap data in PBF format are first processed with OpenTripPlanner to create a street network graph data model. For this purpose, an executable jar-file of OpenTripPlanner is provided along with the source code of the Green Paths software. The resulting graph model with nodes, edges, and respective attributes is imported via comma-separated values (CSV format) to the Green Paths software. The graph_build package uses the model to construct a street network graph that fits the internal graph format of the software. The Green Paths software can read and write graph objects via GraphML file format utilising custom I/O functions, which are written on top of the igraph library (module common.igraph).

During the later stages of the graph build, static external environmental data on traffic noise and greenery are sampled and attached to the edges of the graph via a spatial overlay analysis. These scripts are implemented using mostly procedural programming style.

AQI updater package

The aqi_updater package is needed for fetching, processing, and sampling Air Quality Index (AQI) values from the raster files to the street network graph. It is developed as an independent sibling package next to the gp_server package and can be used from the root of the project (aqi_updater_main.py). While the implementation of the package includes many generic functionalities, the current solution is adjusted to work in the Helsinki Metropolitan Area with the AQI data formats that are described in Table 2.

The aqi_updater reads graph data from the GraphML file and AQI data from a raster file (NetCDF or TIFF) and exports a CSV file that contains a value map of street IDs and respective AQI values. This value map can then be read by the gp_server package to update AQI values to its internal graph object at runtime.

There are two ways of using the aqi_updater, based on the definition in the configuration file of the gp_server package. The options involve either a procedural Python script for processing and sampling a local AQI raster file on demand (see the file aq_data_import.import_static_aqi_data) or a standalone application that fetches AQI data from a remote file server and processes and samples it on a scheduled manner. The latter use case is suitable for using real-time AQI values as demonstrated in the online proof-of-concept instance of the Green Paths routing software for the Helsinki Metropolitan Area (https://green-paths.web.app/).

GP server package

The gp_server package forms the main routing application of the Green Paths software and includes the following functionalities.

Reading routing graph data

The Green Paths software can find five types of routes, including the fastest, safest (for bike, following the OpenTripPlanner capabilities), quietest, and greenest routes, and routes with the freshest air. The three last environmental exposure optimised routing modes are optional. Each enabled routing mode requires the presence of corresponding edge attributes that are listed in the technical documentation. The gp_server package reads the necessary attribute values from the street network graph data in GraphML format, except for the air quality attribute values that are read from the CSV format output of the aqi_updater package.

Environmental impedance function

The software uses Dijkstra’s least cost path routing algorithm, which by default is based on travel time. Travel time is derived from the distance of the edges of the graph and travel mode specific speed coefficients that are defined in the configuration file. To support exposure-optimised routing, we integrated an environmental impedance function to the travel-time-optimised routing algorithm. The function enables calculation of exposure-adjusted edge cost values (Eq. 1) that complement the travel time related base cost of edges:

(1)
Ce=Ct+Ct*ce* s

where Ce is the total (composite) cost of the edge, Ct is the base cost of the edge that is proportional to travel distance and defined speed, Ce is an environmental cost coefficient, and s is an arbitrary sensitivity coefficient for assigning applicable weight(s) for the environmental cost component. The additional environmental cost Ct*ce* s is thus proportional to the value of the environmental variable and travel time. The definition of the environmental cost coefficient Ce depends on the exposure-optimised routing mode. It reflects either the traffic noise level, AQI value, or GVI value in the value range of respective environmental data (see Table 2).

As the units of the cost components are not the same, the combined edge cost is unitless. Edge costs are used only for route optimization, whereas for example route comparison can be done with properties that have a real-world meaning, such as mean noise level.

The sensitivity coefficient s enables multiple alternative routes to be found for a single origin-destination pair. Multiple route suggestions enable responses to the variation of personal preferences, including varying sensitivity to environmental properties or different valuations of travel time. In other words, as it is challenging to define a single best route for everyone, the environmental impedance factor needs to include a sensitivity component that enables the environmental cost and travel time to be balanced. The gp_server package uses a configurable list of sensitivity coefficients for routing several alternative routes. Higher sensitivity coefficients increase the weight of the environmental properties in routing, whereas lower sensitivities result in routes with travel times close to the fastest route. Routing results always include the fastest route by applying a sensitivity coefficient equal to zero. Ideally, exposure-optimised routing can find route(s) of significant improvement in environmental exposure yet with only a limited increase in travel time.

The appropriate list of sensitivity coefficients for each exposure-optimised routing mode varies depending on the value range and spatial variation of the environmental variable. Environmental variables with limited spatial variation require higher sensitivity coefficients to find alternative, exposure-optimised routes.

Configuration

Some of the runtime settings of the Green Paths software can be changed via a simple configuration module in the gp_server package (gp_server.conf). With the configurations, users can (i) define, which graph file is used, (ii) disable or enable either of the two travel modes (walking/biking), (iii) disable or enable exposure-optimised routing modes one by one (traffic noise, greenery or air quality optimized routing), (iv) set the sensitivity coefficients that are used in exposure-optimised routing, (v) set default speed coefficients for travel modes, and (vi) disable or enable the research mode. The latter provides additional exposure information for each route in the results. The differences between the research mode for batch routing and the end-user mode for routing single routes are explained in the technical documentation of the API (see the Availability section).

Start-up of the routing application and routing workflow

To find walking and cycling routes via the least cost path routing algorithm, the Green Paths software applies (edge) cost calculation principles to different travel modes and street types adopted and simplified from the OpenTripPlanner. We implemented a straightforward least cost path routing method: all cost attributes are pre-calculated and assigned to edges during the start-up of the application, i.e., prior to solving the least cost path problem with Dijkstra’s algorithm. This approach makes executing Dijkstra’s algorithm very simple. The downside is that the memory consumption of the application grows quickly along with the number of pre-calculated edge attributes, as an independent cost attribute is needed for each unique combination of travel mode, routing mode, and sensitivity coefficient. The basic edge cost calculation considers length, allows_walking, and allows_biking attributes parsed by OpenTripPlanner for assigning travel time-based costs (base costs) for the two travel modes. Walking with bike is also permitted, to allow streets to be crossed and reaching destinations in walk-only parts of the network (as in OpenTripPlanner). Next, exposure-adjusted edge costs are calculated from edge-level base costs and environmental exposure data using the environmental impedance function. Due to the pre-calculation of cost attributes, several advanced routing features that require dynamic cost calculation within Dijkstra’s algorithm are not supported. These include turning costs for cycling and traffic light penalties.

The start-up of the routing application (gp_server_main.py) initiates the following sequence of actions to prepare the application for handling routing requests:

  1. Graph data from an external GraphML file is read into an in-memory graph object;
  2. Edge and node geometries are read from the graph into GeoPandas GeoDataFrames for fast lookup of the nearest nodes and edges for origins and destinations;
  3. Travel time-based costs are calculated as edge attributes separately for both travel modes (walking & cycling);
  4. Traffic noise-based costs are calculated for both travel modes at different sensitivities and set as edge attributes;
  5. GVI-based costs are calculated for both travel modes at different sensitivities and set as edge attributes;
  6. AQI update data are read and updated to the graph as edge attributes if the CSV-format output either for static or real-time AQI values from the aqi_updater application is available;
  7. AQI-based costs are calculated for both travel modes at different sensitivities and set as edge attributes if the AQI values were updated to the graph under the step 6;
  8. Steps 6 & 7 are repeated in a scheduled manner if real-time AQI data are available.

Steps 4–8 can be disabled from the configuration file of the gp_server package. After successfully executing these steps, the main application is ready to accept routing requests via the API endpoints defined in the module gp_server_main.py (start-up script of the routing application). The sequence of actions that is executed during handling a single routing request is visualised in Figure 2.

Figure 2 

Flowchart of the start-up and the routing workflow of the main routing application (gp_server/gp_server_main.py).

Prior to finding routes, the application finds the nearest edges and nodes to the user-defined origin and destination locations. If the nearest edge is closer than the nearest node, a new temporary node and linking edges are created on the nearest point of the nearest edge. Optimising the resource use is achieved by using a distance difference threshold: if the nearest node is no more than 30 m further than the nearest edge, that node is used as the origin or destination location as opposed to creating a new temporary node.

Since the routing logic is embedded in the pre-calculation of edge costs, routing is executed simply by solving one least cost path problem per each pre-calculated cost attribute as per the user-defined routing options (OD, travel mode, and exposure mode). Routing includes finding both fastest and several exposure optimised routes, as illustrated in Figure 2.

After routing, the identified routes are initially only known as sequences of edge IDs. Complete route information, including the length and environmental exposure properties, are collected and calculated from the graph data by edge IDs. Averaged environmental exposure properties such as mean traffic noise, AQI, and GVI values are then calculated from edge-level properties. Also, accumulated distances within each traffic noise, AQI, and GVI range are calculated and added as route properties.

The maximum number of exposure optimised routes for one origin-destination pair is bounded by the number of sensitivity coefficients that are in use. Since employing the sensitivity coefficients aims to result in routes of little variance in travel time but significant improvement in environmental exposure, many of the identified routes are almost identical by geometry. Therefore, prior to returning the routes to the user, identical and nearly identical routes are filtered out using a geometrical overlay analysis (with 50 m buffers).

API and response schema

The Green Paths software publishes its routing functionality as a RESTful API. The API accepts HTTP GET requests that contain the necessary routing settings as (URL) path variables.

In the case of a routing error, the response status code indicates the type of the error, and the response data contains a descriptive error message. After successful routing, the API returns all route information in GeoJSON FeatureCollection format (Figure 2). Each route features several descriptive properties, including exposure profiles for traffic noise, air quality, and greenery, and general information such as total distance. The API and its usage are documented in more detail in the technical documentation.

Quality control

The software code features several API tests and some unit tests that ensure the basic routing functionality. The testing approach focuses mainly on higher level regression testing (API tests), which allowed heavy refactoring of the architecture as well as implementation details whenever necessary. We automated the test runs as continuous integration pipelines using GitHub Actions. This ensured that the software remained functional before changes were pushed to the main branch.

(2) Availability

Operating system

Linux, OS X, and Windows.

Programming language

Python 3.8.

Additional system requirements

The CPU and memory requirements for the Green Paths software depend primarily on the size of the street network graph data, as the complete graph is loaded to memory at runtime. The size of the graph data file for HMA, including greenery and noise attributes, is roughly 500 MB. Hence, at least 500 + 100 MB memory is needed to run the application successfully. In practice, running several parallel instances of the application is recommended to allow a larger number and concurrent routing requests. Parallelisation can be achieved either with running the application in Docker containers, using multiple Gunicorn workers, or with a mixture of the two.

Dependencies

The Green Paths software requires installation of the following Python libraries: igraph, GeoPandas, Shapely, Flask, Gunicorn, and the sub-dependencies of these. The complete Python environment is described as a YAML environment file and can be easily installed with the Conda package manager.

List of contributors

This software was developed and designed by Joose Helle (UH & SYKE) with support from Age Poom (UH, project management, conceptualisation, testing, and research), Elias Willberg (UH, testing, and research), Tuomas Väisänen (UH, technical support), and Tuuli Toivonen (UH, conceptualisation, and supervision).

Software location

Archive

Name: Zenodo

Persistent identifier: DOI: 10.5281/zenodo.5409403

Licence: MIT licence

Version published: 0.8.0

Date published: 03/09/2021

Code repository

Name: GitHub

Persistent identifier:https://github.com/DigitalGeographyLab/green-path-server

Licence: MIT licence

Version published: 0.8.0

Date published: 03/09/2021 (v0.8.0)

Language

The software and its technical documentation are written in English.

(3) Reuse potential

The published version of the proof-of-concept software for exposure-optimised routing has been developed to work in the Helsinki Metropolitan Area based on the locally available environmental data. A complete installation guide is provided along with the source code, including data download steps for the Helsinki Metropolitan Area. The ready-made sample street network graph for the region includes traffic noise and street-level greenery information.

To reuse the Green Paths software in spatial contexts other than in the Helsinki Metropolitan Area, both OpenStreetMap-based street network data and environmental data are needed. Provided that OpenStreetMap data are available for many cities in a standard format and the application is written with modular Python, the software can be adopted and applied elsewhere, both for research and route planner applications.

A substantial proportion of the software functionality of handling environmental data requires localisation, depending on the available data and their characteristics, such as file formats, value ranges, and spatial extents. For adopting the software to other locations, the need for modification or developing new implementation solutions depends on the similarity of the available data in those locations with the data applied in the current version of the software, specific to the Helsinki Metropolitan Area (sample data and installation guide are provided in the technical documentation). Specifically, local implementation requires adaptation of the packages graph_builder and aqi_updater to match the available data formats and structures. The broad steps for data pre-processing and integration are described in the technical documentation (see the Availability section).

The software has been used in research to analyse multiple exposures during realised mobility and the accessibility of healthy travel environments in Helsinki [see ]. The software is also applied in a prototype end-user route planner Green Paths, accessible at https://green-paths.web.app/. The end-user web application was developed in the European Union funded project Healthy Outdoor Premises for Everyone (UIA HOPE). It visualises the results returned by the API by suggesting multiple routes between the user-defined origin-destination pair. It presents the results separately for walking and cycling, and for quiet, green, and fresh air routes (Figure 3). The development of Green Paths continues now under projects GREENTRAVEL and Urban Airquality 2.0.

Figure 3 

Selected screenshots of the Green Paths routing tool user interface for finding and comparing quiet routes for walking.

Source: https://green-paths.web.app.