Distance calculations

Geocoding

The first step in calculating the distance between two locations is to obtain the geographic coordinates of these locations, which is called geocoding. For this, we use the open-source geocoder Pelias, as well as a database of train stations.

a) Geocoding for air travel

Most airports around the world can be identified by a unique code, assigned by the International Air Transport Association (IATA). To retrieve the location of airports, we use Pelias and search for the IATA code in combination with the keyword “Airport”.

co2calculator.distances.geocoding_airport(iata: IataAirportCode) → Tuple[str, Tuple[float, float], str]

Function to obtain the coordinates of an airport by the IATA code

Parameters:

iata (str) – IATA airport code

Returns:

name, coordinates and country of the found airport

Return type:

Tuple[str, Tuple[float, float], str]

b) Geocoding for train trips

To obtain the coordinates of train stations within Europe, we use the train station database by Trainline.

co2calculator.distances.geocoding_train_stations(loc_dict)

Function to obtain coordinates for a given train station

Parameters:

loc_dict – dictionary describing the location.

The dictionary can have the keys:

   country:        highest-level administrative divisions supported in a search.
                   Only two-letter abbreviations supported
                   e.g., 'DE'

   station_name:   Name of the train station
                   e.g., 'Heidelberg Hbf'

Returns:

Name, country and coordinates of the found location

As you can see above, a dictionary with the keys country and station_name has to be provided for both start and destination.

We use the fuzzy string matching package thefuzz to find the train station in the database which best matches the user input.

c) Geocoding for other trips

For other trips (e.g., car or bus), we use Pelias structured geocoding as included in openrouteservice. This means that the user has different predefined fields to specify an address.

co2calculator.distances.geocoding_structured(loc_dict)

Function to obtain coordinates for a given address

Parameters:

loc_dict – dictionary describing the location.

The dictionary can have the keys:
   country:        highest-level administrative divisions supported in a search.

                   Full country name or two-/three-letter abbreviations supported
                   e.g., Germany / "DE" / "DEU"

   region:         first-level administrative divisions within countries, analogous to states and provinces
                   in the US and Canada
                   e.g., Delaware, Ontario, Ardennes, Baden-Württemberg

   county:         administrative divisions between localities and regions
                   e.g., Alb-Donau-Kreis

   locality:       equivalent to what are commonly referred to as cities
                   e.g., Bangkok, Caracas

   borough:        mostly known in the context of NY, may exist in other cities like Mexico City
                   e.g. Manhattan in NY, Iztapalapa in Mexico City

   postalcode:     postal code; !! Not working in many countries !!

   address:        street name, optionally also house number

   neighbourhood:  vernacular geographic entities that may not necessarily be official administrative
                   divisions but are important nonetheless
                   e.g. Notting Hill in London, Le Marais in Paris

Returns:

Name, country and coordinates of the found location

Good results can be achieved by specifying country, locality and address. Further specifications are usually not needed and can sometimes even negatively affect the geocoding results.

Distance computation

For the computation of distances between places of departure and destination, we use two different approaches, depending on the specified mode of transport:

a) Distance as the crow flies + detour

Calculating the distance as the crow flies (great circle distance) and multiplying by a detour coefficient or adding a detour constant.

The distance as the crow flies is calculated using the haversine formula:

co2calculator.distances.haversine(lat_start: float, long_start: float, lat_dest: float, long_dest: float) → float

Function to compute the distance as the crow flies between given locations

Parameters:

• lat_start (float) – latitude of start

• long_start (float) – Longitude of start

• lat_dest (float) – Latitude of destination

• long_dest (float) – Longitude of destination

Returns:

Distance

Return type:

Kilometer

The transport modes for which this approach is used are listed in the table below, together with their detour parameters.

Detour parameters

	transportation_mode	coefficient	constant [km]
0	bus	1.5	0.0
1	train	1.2	0.0
2	plane	1.0	95
3	ferry	1.0	0.0

b) Road distance

Calculating the road distance using openrouteservice.

This approach is only used for the transport mode car.

Here is an example of how this works using the openrouteservice Python library).

import openrouteservice
from openrouteservice.directions import directions

clnt = openrouteservice.Client(key=ors_api_key)

# coords: list/tuple of locations [lat,long]
route = directions(clnt, coords, profile="driving-car")
distance = route["routes"][0]["summary"]["distance"]