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 |
|
|
| challenging | indicates whether the route allows very tight passes |
|
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 |
via point coordinate as WGS84 latitude,longitude | latitude:-90..90
longitude: -180..180 |
empty |
| vessel | vessel type |
|
|
| attractive | forces routing through attractive areas |
|
0 |
| avoidbridges | indicates to what extend closed bridges are avoided |
|
0 |
|
departuretimestamp or departuredate departuretime |
departure date and time |
|
now |
|
useoperatingtimes |
respect operating times of bridges and locks in the Netherlands |
|
0 |
| avoidopenwater | indicates to what extend big lakes and sea is avoided |
|
0 |
| avoidlocks | indicates to what extend ship locks are avoided |
|
0 |
| avoidbigcanals | indicates to what extend big canals are avoided |
|
0 |
| avoidrules | indicates which areas with a certain legislation are avoided | comma-separated list of:
|
– |
| 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 |
| ignoreblocks | indicates whether legally closed waterways should be ignored |
|
0 |
| avoidobstructions | indicates whether officially announced obstructions should be avoided |
|
0 |
| ignoreengine | indicates whether “no access with engine on” should be ignored |
|
0 |
| ignoreoneway | indicates whether one-way limitations should be ignored |
|
0 |
| ignorenosports | indicates whether limitations for recreation should be ignored |
|
0 |
| ignoreonlysports | indicates whether limitations for professional transport should be ignored |
|
0 |
| language | output language |
|
en |
| allowMastDown | indicates whether you are willing to lower the mast (only effective when minheight != maxheight) |
|
0 |
| includes | indicates items that should be in the response | comma-separated list of:
|
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"
}
