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)
  • warnings
    • CANNOT_FULLY_REACH_DESTINATION: User picked a location that cannot fully be reached within 200m.
    • DARK_ARRIVAL: Arrival will be in the dark.
    • LIGHT_ARRIVAL: Arrival will be at daylight.
    • NEEDS_PERMIT: There is a (local) permit needed to pass here.
    • NEEDS_FLEMISH_PERMIT: A permit is needed to pass through Flanders, given your ship size.
    • ENGINE_FORBIDDEN: o engine can be used here.
    • AGAINST_TRAFFIC_DIRECTION: You allowed and will go against the traffic here.
    • PASSAGE_BLOCKED: Officially you cannot pass here, technically you could.
    • OBSTRUCTION: There is an obstruction here that may block you.
    • OUT_OF_FUEL: Future feature: Given your fuel/electric charge, you need to refuel around here.
    • ABOVE_MAX_SPEED: Here you would go faster than allowed, given your nominal speed and willingness to ignore it.
    • NEEDS_RESERVATION: You need to make a reservation to pass here.
    • CANOE_THROUGH_BIG_LOCK: Your canoe can pass the lock but it will be dangerous.
    • NO_LEISURE_ENTRY: No entry for sports/recreation vessels.
    • NO_CARGO_ENTRY: No entry for cargo ships.
    • THROUGH_SEA: You want to avoid sea but here you need to cross the sea.
    • UNKNOWN_BRIDGE_HEIGHT: It is unsure whether you can pass here – data missing.
    • LONG_WAITING_TIME: You may have to wait long (>2h) to pass.
    • THROUGH_OPEN_WATER: You want to avoid big water areas but you need to cross it here.
    • THROUGH_BIG_CANAL: You want to avoid big canals but you need to cross it here.
    • CHALLENGING_PASSAGE: There is very little space to pass, you will fit but it takes (local) experience.
    • NEED_ACTUAL_MAP: It is strongly advised to have support from the latest official maps here.
    • DANGEROUS_CROSSING: This crossing is tagged as dangerous by the authorities.
    • TRAFFIC_SEPARATION_AREA: You will pass a traffic separation zone here.
    •  LICENSE_KVB2: Dutch “Klein Vaarbewijs II” is needed here.
    • LICENSE_BVSP: “Sport Patent” for small boats on Rijn up from Spijk/NL into Germany is needed here.
    • RULE_RPR: You want to avoid areas with “Rijnvaart Politiereglement NL legislation” but you need to cross here.
    • RULE_GM: You want to avoid areas with “Grensmaas NL legislation” but you need to cross here.
    • RULE_ED: You want to avoid areas with “Eems/Dollard NL legislation” but you need to cross here.
    • RULE_WS: You want to avoid areas with “Westerschelde NL legislation” but you need to cross here.
    • RULE_BVA: You want to avoid areas with “Dutch Sea legislation” but you need to cross here.
    • RULE_TZ: You want to avoid areas with “12 miles territorial legislation” but you need to cross here.
    • RULE_KGT: You want to avoid areas with “Canal Gent-Terneuzen NL legislation” but you need to cross here.
    • TIDAL: You experience tidal effects here. Not implemented yet, Feb 2024.
    • CURRENT: You experience streams/currents here. Not implemented yet, Feb 2024.
    • TIMEZONE_CHANGED: You pass a timezone here (check ETA).
  • nodes: points along the route
  • arcs: stretches with pass types:
    • 0: regular stretch
    • 11: lock
    • 12: fixed bridge
    • 13: canoe carry-over
    • 14: ferry crossing
    • 15: boat ramp
    • 16: movable bridge
    • 17: tunnel
    • 21: cable ferry
  • and arc types:
    • 4: very big canal for sea ships
    • 5: big canal or river for big cargo ships
    • 7: canal for big yachts and cargo ships
    • 8: canal for cabin cruisers, perhaps yachts not too big
    • 9: small canal for small open boats
    • 10: canoe ditch
  • gtl is ground truth language:
    • 0: none
    • 1: Dutch
    • 2: Frisian
    • 3: German
    • 4: French
    • 5: English
    • 6: Spanish
    • 7: Danish
    • 8: Italian
    • 9: Japanese
    • 10: Chinese
    • 11: Luxembourgish
    • 12: Swedish
    • 13: Polish
    • 14: Czech
    • 15: Flemish
    • 16: Portuguese
    • 17: Greek
    • 18: Slovenian
    • 19: Croatian
    • 20: Montenegrin
    • 21: Serbian
    • 22: Albanian
    • 23: Bosnian
    • 24: Turkish
    • 25: Slovak
    • 26: Hungarian
    • 27: Romanian
    • 28: Ukrainian
    • 29: Bulgarian
    • 30: Icelandic
    • 31: Gaelic
    • 32: Maltese
    • 33: Welsh
    • 34: Norwegian
    • 35: FInnish
    • 36: Scottish
 
 

Bitnami