The MarinePlan boat routing API 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.
Please note there are several flags to influence avoidance of rules, obstructions, ignoring all kinds of situations.
In addition, it will report which license is required such as the Dutch Klein Vaarbewijs (KVB) and which local legislation applies such as the Dutch RPR and BPR. The engine is able to avoid these areas when the captain does not meet these requirements or has a preference to avoid these for personal reasons.
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
The API will use http(s)://api.marineplan.com as the base path. For emergencies, there is a fallback to http(s)://marineplan.net (please note: no api subdomain here).
| parameter | description | values | default value |
|---|---|---|---|
| version | API version | 1 | |
| ext | output format | JSON: for B2B applications, apps and web sites GPX: for output used for plotters and in-dash applications KML: for Google Earth PNG: for publications SVG: for inclusion into other artwork HTML: for printing purposes | – |
| challenging | indicates whether the route allows very tight passes, narrow creeks or shallow ditches and other challenging situations | 0=safe route 1=accept 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 up to via100 | via point coordinate as WGS84 latitude,longitude | latitude:-90..90 longitude: -180..180 | empty |
| vessel | vessel type | 6=canoe 5=open boat/sloop 4=cabin cruiser (small yacht) 3=bigger yacht 2=cargo ship | |
deprecated | 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 | departure timestamp 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 |
| ignorespeedlimit | ignores speed limits and uses given or assumed nominal vessel speed | 0=respect 1=ignore | 0 |
| ignoredepth | ignores depth (use only in rare cases when depth is assumed wrong) | 0=respect 1=ignore | 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 DE FR DA IT PT ES FY SV NL | 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 |
| key | API secret key, to be requested from MarinePlan | UUID | – |