searoute 1.1.0

A python package for generating the shortest sea route between two points on Earth.

---

Searoute py

An python package for generating the shortest sea route between two points on Earth.

If points are on land, the function will attempt to find the nearest point on the sea and calculate the route from there.

Not for routing purposes! This library was developed to generate realistic-looking sea routes for visualizations of maritime routes, not for mariners to route their ships.

Installation

pip install searoute

Usage

import searoute as sr

#Define origin and destination points:
origin = [0.3515625, 50.064191736659104]

destination = [117.42187500000001, 39.36827914916014]


route = sr.searoute(origin, destination)
# > Returns a GeoJSON LineString Feature
# show route distance with unit
print("{:.1f} {}".format(route.properties['length'], route.properties['units']))

# Optionally, define the units for the length calculation included in the properties object.
# Defaults to km, can be can be 'm' = meters 'mi = miles 'ft' = feets 'in' = inches 'deg' = degrees
# 'cen' = centimeters 'rad' = radians 'naut' = nauticals 'yd' = yards
routeMiles = sr.searoute(origin, destination, units="mi")

Example with more parameters :

## Using all parameters, wil include ports as well
route = sr.searoute(origin, destination, append_orig_dest=True, restrictions=['northwest'], include_ports=True, port_params={'only_terminals':True, 'country_pol': 'FR', 'country_pod' :'CH'})

returns :

{
  "geometry": {
    "coordinates": [],
    "type": "LineString"
  },
  "properties": {
    "duration_hours": 461.88474412693756,
    "length": 20529.85310695412,
    "port_dest": {
      "cty": "China",
      "name": "Tianjin",
      "port": "CNTSN",
      "t": 1,
      "x": 117.744852,
      "y": 38.986802
    },
    "port_origin": {
      "cty": "France",
      "name": "Le Havre",
      "port": "FRLEH",
      "t": 1,
      "x": 0.107054,
      "y": 49.485998
    },
    "units": "km"
  },
  "type": "Feature"
}

Parameters

origin
Mandatory. An array of 2 floats representing longitude and latitude i.e : [{lon}, {lat}]

destination
Mandatory. An array of 2 floats representing longitude and latitude i.e : [{lon}, {lat}]

units
Optional. Default to km = kilometers, can be m = meters mi = miles ft = feets in = inches deg = degrees cen = centimeters rad = radians naut = nauticals yd = yards

speed_knot
Optional. Speed of the boat, default 24 knots

append_orig_dest
Optional. If the origin and destination should be appended to the LineString, default is False

restrictions
Optional. List of passages to be restricted during calculations. Possible values : babalmandab, bosporus, gibraltar, suez, panama, ormuz, northwest; default is ['northwest']

include_ports
Optional. If the port of load and discharge should be included, default is False

port_params
Optional. If include_ports is True then you can set port configuration for advanced filtering :

• only_terminals to include only terminal ports, default False
• country_pol country iso code (2 letters) for closest port of load, default None. When not set or not found, closest port is based on geography.
• country_pod country iso code (2 letters) for closest port of discharge, default None. When not set or not found, closest port is based on geography.

default is {}

Returns

GeoJson Feature

Credits

• NetworkX, a Python package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks.
• turfpy, a Python library for performing geospatial data analysis which reimplements turf.js.
• OSMnx, for geo-spacial networks.
• Eurostat's Searoute Java library

Change Log

1.0.2 (30/09/2022)

• First Release, published module

1.0.3 (04/10/2022)

• changed the core of the calculation to osmnx library for better perfomance
• making 1.0.2 obsolete
• added duration measurement together with length in the LineString properties

1.0.4 (04/10/2022)

• fix requirements of the module

1.0.5 (04/10/2022)

• Adjusted network (.json) by connecting all LineStrings in order to return a route from any location to any location

1.0.6 (05/10/2022)

• Improved network connectivity

1.0.7 (13/10/2022)

• Improved network connectivity
• Connection points were not adjusted

1.0.8 (25/10/2022)

• Improved network connectivity
• Added append_orig_dest parameter as input to append origin and destination points to the LineString
• Updated README.md

1.0.9 (04/01/2023)

• Improved network connectivity
• Added restrictions parameter as input to control restrictiveness of connections due to different reasons
• Updated README.md

1.1.0 (23/05/2023)

• Improved network connectivity
• Added new feature : closest port of load and port of discharge
• Updated README.md