Geography Utils

To make handling of mobility and geodata easier, trackintel features several geographic utility functions and distance functions for points and trajectories

trackintel.geogr.distances.calculate_distance_matrix(X, Y=None, dist_metric='haversine', n_jobs=0, **kwds)[source]

Calculate a distance matrix based on a specific distance metric.

If only X is given, the pair-wise distances between all elements in X are calculated. If X and Y are given, the distances between all combinations of X and Y are calculated. Distances between elements of X and X, and distances between elements of Y and Y are not calculated.

  • X (GeoDataFrame (as trackintel staypoints or triplegs)) –

  • Y (GeoDataFrame (as trackintel staypoints or triplegs), optional) –

  • dist_metric ({'haversine', 'euclidean', 'dtw', 'frechet'}) –

    The distance metric to be used for calculating the matrix.

    For staypoints, common choice is ‘haversine’ or ‘euclidean’. This function wraps around the pairwise_distance function from scikit-learn if only X is given and wraps around the scipy.spatial.distance.cdist function if X and Y are given. Therefore the following metrics are also accepted:

    via scikit-learn: [‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’, ‘manhattan’]

    via scipy.spatial.distance: [‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’]

    For triplegs, common choice is ‘dtw’ or ‘frechet’. This function uses the implementation from similaritymeasures.

  • n_jobs (int) – Number of cores to use: ‘dtw’, ‘frechet’ and all distance metrics from pairwise_distance (only available if only X is given) are parallelized.

  • **kwds – optional keywords passed to the distance functions.


D – matrix of shape (len(X), len(X)) or of shape (len(X), len(Y)) if Y is provided.

Return type



>>> calculate_distance_matrix(staypoints, dist_metric="haversine")
>>> calculate_distance_matrix(triplegs_1, triplegs_2, dist_metric="dtw")
trackintel.geogr.distances.meters_to_decimal_degrees(meters, latitude)[source]

Convert meters to decimal degrees (approximately).

  • meters (float) – The meters to convert to degrees.

  • latitude (float) – As the conversion is dependent (approximatively) on the latitude where the conversion happens, this needs to be specified. Use 0 for the equator.


An approximation of a distance (given in meters) in degrees.

Return type



>>> meters_to_decimal_degrees(500.0, 47.410)
trackintel.geogr.distances.check_gdf_planar(gdf, transform=False)[source]

Check if a GeoDataFrame has a planar or projected coordinate system.

Optionally transform a GeoDataFrame into WGS84.

  • gdf (GeoDataFrame) – input GeoDataFrame for checking or transform

  • transform (bool, default False) – whether to transform gdf into WGS84.


  • is_planer (bool) – True if the returned gdf has planar crs.

  • gdf (GeoDataFrame) – if transform is True, return the re-projected gdf.


>>> from trackintel.geogr.distances import check_gdf_planar
>>> check_gdf_planar(triplegs, transform=False)

Calculate the length of linestrings using the haversine distance.


gdf (GeoDataFrame with linestring geometry) – The coordinates are expected to be in WGS84


length – The length of each linestring in meters

Return type



>>> from trackintel.geogr.distances import calculate_haversine_length
>>> triplegs['length'] = calculate_haversine_length(triplegs)

Point distances

trackintel.geogr.point_distances.haversine_dist(lon_1, lat_1, lon_2, lat_2, r=6371000, float_flag=False)[source]

Compute the great circle or haversine distance between two coordinates in WGS84.

Serialized version of the haversine distance.

  • lon_1 (float or numpy.array of shape (-1,)) – The longitude of the first point.

  • lat_1 (float or numpy.array of shape (-1,)) – The latitude of the first point.

  • lon_2 (float or numpy.array of shape (-1,)) – The longitude of the second point.

  • lat_2 (float or numpy.array of shape (-1,)) – The latitude of the second point.

  • r (float) – Radius of the reference sphere for the calculation. The average Earth radius is 6’371’000 m.

  • float_flag (bool, default False) – Optimization flag. Set to True if you are sure that you are only using floats as args.


An approximation of the distance between two points in WGS84 given in meters.

Return type

float or numpy.array


>>> haversine_dist(8.5, 47.3, 8.7, 47.2)