Online Routing

The route planner service will compute a number of routes based on the given input. The routing engine is aware of one-way entries, blocked entries, blocked entries for motorized traffic, blocked entries for recreation ships, bridge and ship lock dimensions and opening hours, canal and lake depth, river current speed, maximum speeds, ship dimensions and many other properties. It will compute routing instructions as well as distance, estimated time of arrival (ETA) and the expected fuel or battery consumption.

In addition, it will report which license is required such as Klein Vaarbewijs (KVB) and which local legislation applies such as RPR and BPR. The engine is able to avoid these areas when the captain does not meet these requirements.

The output can be in different formats:

  • JSON (standard for computer-to-computer traffic)
  • GPX (ideal exchange format for GPS and chart plotters)
  • KML (good match for overlaying on a Google Map)
  • PNG (best for sharing in social media, on websites)
  • SVG (best vector format for using in presentations and artwork)

API

Output will be either JSON or GPX (RTE subformat):

GET http(s)://api.marineplan.com/api/routing/<version>/plan.<ext>?<parameters>

Parameters

parameter description values default value
version API version 1  
ext output format
  • JSON
  • GPX
  • KML
  • PNG
  • SVG
 
challenging indicates whether the route allows very tight passes
  • 0=safe route
  • 1=challenging
1
from departure coordinate as WGS84 latitude,longitude latitude:-90..90

longitude: -180..180

to destination coordinate as WGS84 latitude,longitude latitude:-90..90

longitude: -180..180

via1
via2
etc.

via point coordinate as WGS84 latitude,longitude latitude:-90..90

longitude: -180..180

empty
vessel vessel type
  • 6=canoe
  • 5=open boat
  • 4=cruiser (small yacht)
  • 3=yacht
  • 2=cargo ship
 
attractive forces routing through attractive areas
  • 0=regular
  • 1=attractive
0
avoidbridges indicates to what extend closed bridges are avoided
  • 0=not
  • 1..4=moderate
  • 5=harshly avoided
0

departuretimestamp

or

departuredate

departuretime

departure date and time
  • departuretimestamp as seconds since 01-01-1970 UTC
  • departuredate as local date EST yyyy-MM-dd
  • departuretime as local time EST HH:mm
now

useoperatingtimes

respect operating times of bridges and locks in the Netherlands
  • 0=ignore
  • 1=respect
0
avoidopenwater indicates to what extend big lakes and sea is avoided
  • 0=not
  • 1..4=moderate
  • 5=harshly avoided
0
avoidlocks indicates to what extend ship locks are avoided
  • 0=not
  • 1..4=moderate
  • 5=harshly avoided
0
avoidbigcanals indicates to what extend big canals are avoided
  • 0=not
  • 1..4=moderate
  • 5=harshly avoided
0
avoidrules indicates which areas with a certain legislation are avoided comma-separated list of:

 

  • rpr (Rijnvaart Politiereglement, NL)
  • tz (Scheepvaartreglement Ter Zee)
  • tss (Traffic Separation Scheme)
  • kvb2 (Klein Vaarbewijs II, NL)
  • kgt (Kanaal Gent-Terneuzen, NL)
  • ed (Eems-Dollard, NL)
  • ws (Westerschelde, NL)
  • bvsp (Rijnpatent)
  • gm (Grensmaas, NL)
  • sea (effectively avoids all sea waters)
alternatives number of alternative routes 1..5 0
width ship beam (width) in meters 1..30 depends on vessel type
weight ship weight in kilograms 1..100,000 depends on vessel type
depth ship draft (depth) in meters 0.1..20 depends on vessel type
length ship length in meters 1..300 depends on vessel type
minheight minimum height of ship (mast down) in meters (air draught) 0.2..60 depends on vessel type
maxheight minimum height of ship (mast up) in meters (air draught) 0.2..60 depends on vessel type
maxspeed maximum speed in km/h 1..90 depends on vessel type
nominalspeed cruising speed in km/h 1..90 depends on vessel type
consumptionperhour consumption per hour at nominal speed liter/hour (fueltype=LIQUID) or Watt (fueltype=ELECTRIC) 0
fueltype engine fuel type for consumption calculation
  • NONE
  • ELECTRIC
  • LIQUID
NONE
ignoreblocks indicates whether legally closed waterways should be ignored
  • 0=respect
  • 1=ignore
0
avoidobstructions indicates whether  officially announced obstructions should be avoided
  • 0=ignore
  • 1=respect
0
ignoreengine indicates whether “no access with engine on”  should be ignored
  • 0=respect
  • 1=ignore
0
ignoreoneway indicates whether one-way limitations should be ignored
  • 0=respect
  • 1=ignore
0
ignorenosports indicates whether limitations for recreation should be ignored
  • 0=respect
  • 1=ignore
0
ignoreonlysports indicates whether limitations for professional transport should be ignored
  • 0=respect
  • 1=ignore
0
language output language
  • en: English
  • nl: Dutch
  • fy: Frisian
  • de: German
  • fr: French
en
allowMastDown indicates whether you are willing to lower the mast
(only effective when minheight != maxheight)
  • 0=mast stays up
  • 1=mast goes down if needed
0
includes indicates items that should be in the response comma-separated list of:

 

  • parameters (repetition of the input parameters)
  • summary (route summary with e.g. length, ETA)
  • nodes (geo-points as a polyline)
  • arcs (vectors with meta information)
  • guidance (detailed instructions)
  • stops (passes that possibly force to vessel to stop, such as bridges and locks)
parameters, summary, nodes, arcs, stops
API-key API secret key, to be requested from MarinePlan    

Response

A sample output in a web environment would look like this example.

The response contains:

  • a copy of the input parameters
  • a summary with statistics
  • polyline of the route(s)
  • guidance instructions (with time and distance, as well as warnings)
{
	"planParameters": {
		"from": {
			"latitude": 52.214733,
			"longitude": 4.610448
		},
		"to": {
			"latitude": 52.214397,
			"longitude": 4.605116
		},
		"planningCriteria": {
			"planningType": "FASTEST",
			"vessel": {
				"vesselType": "CONSOLE_BOAT",
				"depthMeters": 0.5,
				"widthMeters": 1.8,
				"weightKg": 300.0,
				"minHeightMeters": 0.65,
				"maxHeightMeters": 0.65,
				"lengthMeters": 5.6,
				"nominalSpeedKmh": 6.0,
				"maxSpeedKmh": 9.0,
				"consumptionPerHour": 0.0,
				"fuelType": "NONE"
			},
			"planningMargins": {
				"depth": 0.2,
				"width": 0.05,
				"height": 0.05,
				"length": 0.1
			},
			"departureTimeSeconds": 64843,
			"allowChallengingRoutes": true,
			"numberOfAlternatives": 0,
			"ignoreOneWay": false,
			"ignoreNoLeisureAccess": false,
			"ignoreNoEngineAccess": false,
			"allowMastDown": true,
			"ignoreSpeedLimit": false,
			"userAvoids": [],
			"vias": []
		},
		"language": "nl"
	},
	"routes": [{
		"summary": {
			"from": {
				"latitude": 52.214733,
				"longitude": 4.610448
			},
			"to": {
				"latitude": 52.214397,
				"longitude": 4.605116
			},
			"departureName": "Ringvaart, Haarlemmermeer, Noord-Holland",
			"destinationName": "Kaag en Braassem, Zuid-Holland",
			"distanceMeters": 382,
			"eta": "18:01",
			"timeSeconds": 33,
			"consumption": 0.0,
			"consumptionUnit": ""
		},
		"planResult": "OK",
		"guidance": {
			"instructions": [{
				"type": "DEPART",
				"localTime": "18:01",
				"timeSeconds": 0,
				"offsetMeters": 0,
				"point": {
					"latitude": 52.214733,
					"longitude": 4.610448
				},
				"direction": 278,
				"printableDirection": "W",
				"location": "Ringvaart, Vredeburg",
				"isReachable": true
			}, {
				"type": "TURN_LEFT",
				"localTime": "18:03",
				"timeSeconds": 159,
				"offsetMeters": 226,
				"point": {
					"latitude": 52.214476,
					"longitude": 4.606704
				},<tr>
<td>to</td>
<td>destination coordinate as WGS84 latitude,longitude</td>
<td>latitude:-90..90
<p> </p>
<p>longitude: -180..180</p>
</td>
<td> </td>
</tr> "direction": 224, "printableDirection": "SW", "location": "Ringvaart, Vredeburg", "isReachable": true }, { "type": "ARRIVE", "localTime": "18:04", "timeSeconds": 225, "offsetMeters": 376, "point": { "latitude": 52.214397, "longitude": 4.605116 }, "direction": 0, "printableDirection": "", "location": "Ringvaart, Nieuwe Wetering", "isReachable": true }] }, "nodes": [{ "latitude": 52.214733, "longitude": 4.610448 }, { "latitude": 52.214764, "longitude": 4.607058 }, { "latitude": 52.214476, "longitude": 4.606704 }, { "latitude": 52.214389, "longitude": 4.606511 }, { "latitude": 52.214397, "longitude": 4.605116 }], "arcs": [{ "passType": 0, "arcType": 7, "flags": 0, "isReachable": true, "objectName": "", "name": "Ringvaart" }, { "passType": 0, "arcType": 9, "flags": 0, "isReachable": true, "objectName": "", "name": "Ringvaart" }, { "passType": 0, "arcType": 9, "flags": 16, "isReachable": true, "objectName": "", "name": "Ringvaart" }, { "passType": 0, "arcType": 9, "flags": 16, "isReachable": true, "objectName": "", "name": "" }] }], "planResult": "OK" }
 

Bitnami