REST API

Vessel Routing API

Generate a navigable maritime route between terminal points while considering vessel draft, intermediate waypoints and optional Emission Control Area avoidance.

Endpoint

POST · https://api.routing.bluegreenintelligence.com/v1/query

Authentication

x-api-key: YOUR_API_TOKEN
Content-Type: application/json

Request

{
  "startlat": 1.147161,
  "startlon": 103.777511,
  "endlat": 25.170492,
  "endlon": 56.378533,
  "draft": 12,
  "avoidECA": false,
  "waypoints": [[8.583573, 89.439206]],
  "coerceerrors": false
}

Request fields

FieldTypeRequiredDescription
startlatfloatYesStarting latitude in WGS84 decimal degrees, from -90 to 90.
startlonfloatYesStarting longitude in WGS84 decimal degrees, from -180 to 180.
endlatfloatYesDestination latitude in WGS84 decimal degrees, from -90 to 90.
endlonfloatYesDestination longitude in WGS84 decimal degrees, from -180 to 180.
draftfloatYesVessel draft in metres. Used to apply navigable-depth restrictions.
avoidECAbooleanYesWhen true, attempts to avoid Emission Control Areas.
waypointsarrayYesOrdered intermediate coordinates in [lat, lon] format. May be empty; maximum 10.
coerceerrorsbooleanYesOverrides terminal-point navigability validation and forces route generation. Route accuracy may be affected.
Use coerceerrors cautiously. Normal routing requires both terminal points to be navigable for the specified draft.

Route capabilities

  • Draft restrictions: Routes avoid shallow water based on the supplied vessel draft.
  • ECA avoidance: Optional avoidance of Emission Control Areas.
  • Custom waypoints: Up to ten ordered waypoints may be used to guide the route.
  • Route metadata: Returned points include sequence and node-type information such as Start, TSS, Open ocean and End.

Quota usage

Each routing API call consumes exactly one quota unit, regardless of route complexity, distance, number of waypoints or response size.

quota_used = 1 per API call

Example requests

Simple route
{
  "startlat": 24.50,
  "startlon": 54.20,
  "endlat": 0.5,
  "endlon": 0,
  "draft": 10,
  "avoidECA": false,
  "waypoints": [],
  "coerceerrors": false
}
Route with ECA avoidance
{
  "startlat": 49.7990989,
  "startlon": -8.8450002,
  "endlat": 40.7128,
  "endlon": -74.0060,
  "draft": 10,
  "avoidECA": true,
  "waypoints": [],
  "coerceerrors": false
}
Route with custom waypoints
{
  "startlat": 1.147161,
  "startlon": 103.777511,
  "endlat": 25.170492,
  "endlon": 56.378533,
  "draft": 12,
  "avoidECA": false,
  "waypoints": [[8.583573, 89.439206], [9.643339, 65.105020]],
  "coerceerrors": false
}

Response

The route is returned as a GeoJSON FeatureCollection. GeoJSON coordinates are ordered as longitude, latitude. Plot features in ascending seq order.

{
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {"type": "Point", "coordinates": [103.7570, 1.1368]},
        "properties": {"seq": 0, "nodetype": "Start"}
      },
      {
        "type": "Feature",
        "geometry": {"type": "Point", "coordinates": [103.8182, 1.1827]},
        "properties": {"seq": 1, "nodetype": "TSS"}
      }
    ]
  },
  "quota_remaining": 1498
}

Integration notes

  • Coordinates use WGS84 decimal degrees.
  • GeoJSON coordinates are ordered as longitude, latitude.
  • Plot returned points in sequence order.
  • Implement timeout and retry handling for complex routes.
  • Route points can be visualized with mapping libraries such as Leaflet, Google Maps or Mapbox.

Request and response JSON

Example input JSON
{
  "startlat": 1.147161,
  "startlon": 103.777511,
  "endlat": 25.170492,
  "endlon": 56.378533,
  "draft": 12,
  "avoidECA": false,
  "waypoints": [],
  "coerceerrors": false
}
Example output JSON
{
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {"type": "Point", "coordinates": [103.7570, 1.1369]},
        "properties": {"seq": 0, "nodetype": "Start"}
      }
    ]
  },
  "quota_remaining": 1498
}

Quick start

curl -X POST "https://api.routing.bluegreenintelligence.com/v1/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d '{
    "startlat": 1.147161,
    "startlon": 103.777511,
    "endlat": 25.170492,
    "endlon": 56.378533,
    "draft": 12,
    "avoidECA": false,
    "waypoints": [[8.583573, 89.439206], [9.643339, 65.105020]],
    "coerceerrors": false
  }'

Custom quota

For temporary quota increases, enterprise fleet volumes or custom commercial requirements, contact operations@bluegreenintelligence.com. Include the expected route volume and fleet profile.

Live API demo

Generated request

The API key remains in this browser tab and is sent only to the selected API endpoint.