Aquaplot API Docs

Overview

The Aquaplot API calculates ship routes and nautical distances between coordinates, validates whether coordinates can be used for routing, and searches Aquaplot's public maritime location database.

All requests use HTTPS and the production base URL:

https://api.aquaplot.com/v1

Coordinates are decimal degrees. Route, distance, and validation path parameters use longitude first, then latitude:

/from/{from_lng}/{from_lat}/to/{to_lng}/{to_lat}

JSON request bodies use explicit lat and lng fields. GeoJSON response geometries use standard GeoJSON coordinate order: [longitude, latitude].

Authentication

Create an API key in Aquaplot Console and send it with every API request using the standard Bearer token pattern.

curl \
  -H "Authorization: Bearer <token>" \
  https://api.aquaplot.com/v1/locations/hamburg

If authentication fails, the API returns 401 Unauthorized. Treat API keys like passwords and keep them out of client-side code, public repositories, and logs.

Routes

Use route endpoints when you need the calculated route path as GeoJSON. A successful response is a GeoJSON FeatureCollection; each feature contains a LineString geometry and route metrics in properties. Distance metrics, including distance.total and total_length, are reported in nautical miles.

GET /v1/route/from/{from_lng}/{from_lat}/to/{to_lng}/{to_lat}

Calculates one route from coordinates in the URL. Optional query parameters control canal, strait, risk-area, and validation behavior.

curl \
  -H "Authorization: Bearer <token>" \
  "https://api.aquaplot.com/v1/route/from/4.9041/52.3676/to/103.8198/1.3521?suez=true&panama=false&eca=minimize"

{
  "type": "FeatureCollection",
  "status": "ok",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "aqpRequestId": "",
        "id": "",
        "total_length": 8280.42,
        "distance": {
          "total": 8280.42
        }
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [4.9041, 52.3676],
          [103.8198, 1.3521]
        ]
      }
    }
  ],
  "errors": []
}

POST /v1/routes

Calculates up to 100 routes in one request. Use id to correlate each returned feature or error with your own shipment, estimate, or job record.

curl \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "id": "ams-sin-001",
        "from": { "lng": 4.9041, "lat": 52.3676 },
        "to": { "lng": 103.8198, "lat": 1.3521 },
        "options": {
          "suez": "true",
          "panama": "false",
          "eca": "minimize"
        }
      }
    ]
  }' \
  https://api.aquaplot.com/v1/routes

Batch responses use the same FeatureCollection shape as single-route responses. Successful route features appear in features; per-route calculation failures appear in errors with the original request and a message. A response can contain both successful features and route errors when only part of a batch fails.

Distance

Use the distance endpoint when your integration needs the route distance and can use the single-route URL shape. It returns the same GeoJSON FeatureCollection format as the route endpoint, with one route feature.

GET /v1/distance/from/{from_lng}/{from_lat}/to/{to_lng}/{to_lat}

curl \
  -H "Authorization: Bearer <token>" \
  "https://api.aquaplot.com/v1/distance/from/4.9041/52.3676/to/103.8198/1.3521?autovalidate=true"

{
  "type": "FeatureCollection",
  "status": "ok",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "total_length": 8280.42,
        "distance": {
          "total": 8280.42
        }
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [4.9041, 52.3676],
          [103.8198, 1.3521]
        ]
      }
    }
  ],
  "errors": []
}

Read the distance in nautical miles from features[0].properties.distance.total. total_length is also available for integrations that already use that field. The geometry is included so distance consumers can still inspect or display the path used for the calculation.

Validation

Validation tells you whether coordinates are suitable for route calculations. Use it before routing when coordinates come from user input, third-party geocoding, AIS data, or another source that may place points on land or outside navigable water.

GET /v1/validate/{lng}/{lat}

curl \
  -H "Authorization: Bearer <token>" \
  https://api.aquaplot.com/v1/validate/4.9041/52.3676

{
  "status": "ok",
  "is_valid": true,
  "suggestion": [4.9041, 52.3676],
  "moved_by": 0,
  "validatedLatlng": {
    "lat": 52.3676,
    "lng": 4.9041
  }
}

POST /v1/validate

Validates up to 100 coordinates in one request and returns results in the same order as the submitted requests array.

curl \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "lng": 4.9041, "lat": 52.3676 },
      { "lng": 103.8198, "lat": 1.3521 }
    ]
  }' \
  https://api.aquaplot.com/v1/validate

[
  {
    "status": "ok",
    "is_valid": true,
    "suggestion": [4.9041, 52.3676],
    "moved_by": 0,
    "validatedLatlng": {
      "lat": 52.3676,
      "lng": 4.9041
    }
  }
]

When is_valid is false, use suggestion or validatedLatlng when present to show a corrected nearby routable point. moved_by reports the correction distance in meters.

Locations

Use location search to help users find ports and known maritime locations. Search is case-insensitive and matches by name or UN/LOCODE substring. Queries must be 2-32 characters and results are limited to 20 matches.

GET /v1/locations/{name}

curl \
  -H "Authorization: Bearer <token>" \
  https://api.aquaplot.com/v1/locations/hamburg

[
  {
    "name": "Hamburg",
    "latlng": {
      "lat": 53.5461,
      "lng": 9.9661
    },
    "country": "Germany",
    "locode": "DEHAM",
    "type": "port"
  }
]

Each result includes name, latlng, and type. country and locode are returned when known.

Errors

For request-level failures, the API returns an HTTP status code and a JSON error object. Route batch calculation errors can also appear inside a successful 200 response under the top-level errors array.

{
  "status": "error",
  "reason": "invalid_request"
}

For production integrations, log the endpoint, HTTP status, response body, and your request identifier, but do not log API tokens or sensitive customer payloads.

OpenAPI

The OpenAPI document is the canonical machine-readable API reference. Use it to generate clients, inspect schemas, or import Aquaplot into API tooling.

/api/openapi.yaml

The schema includes all public endpoints, request bodies, response schemas, authentication requirements, and supported routing options.