Introduction

Aquaplot lets you compute distances and routes for ships. The API allows you to retrieve distances between any two coordinates in water. You can enter coordinates manually or choose from our port database, which contains over 12.000 locations including ports, offshore installations etc. Read more about the services we offer at aquaplot.com

Version

The API is currently on version 1 (v1), production ready and used by businesses around the world. We will not introduce any breaking changes unless absolutely necessary and not without proper notice to those that use the API.

Timeouts

Most calculations do not take longer than a few hundred milliseconds. In exceptional cases, calculations may take a few seconds. All our requests have a hard timeout of 10 seconds. If you don't get a response afterwards, there must be an issue with the network connection.

Authentication and Request Tokens

To authorize, use this code:

# With shell, you can just pass your credentials
# to cUrl. Replace 'user' and 'secret' with the
# credentials from your license
curl "<some_url>"\
  -u "user:secret"

Aquaplot API uses simple HTTP authentication. You find your license credentials by browsing to your account page and clicking on more for one of your licenses. Make sure to call the API via HTTPS.

Every license has a quota of request tokens. The amount of available tokens per day, month or year depends on your purchased plan. The amount of available tokens per time period can be -1, which means there is no limit in place. Different API requests require different amounts of tokens. Only successful requests will reduce your quota. A request has been successful, if our server replies with a HTTP-200 response code. Internal server problems and timeouts will not have a negative impact on your quota. You find information on the number of required tokens of each request in this document.

Request Rate Limits

Depending on your API license, request throttling is enforced. These mechanisms work independent from the request token concept. There can be rate limits for:

  • Number of requests in a minute
  • Number of requests in an hour
  • Number of requests running concurrently
  • Minimum waiting time between two consecutive requests
  • Request patterns that violate our Terms of Service (e.g. we identify a DOS attack)

Check the details page of your license on your account page. Whenever one of these limits is reached, we will return with a HTTP status 429. Limits are less strict for computationally cheap requests like /geocode, /validate and /quota.

Response Codes

A general guide on how we use HTTP status codes:

Status Code Meaning
200 Success
301 Permanently Moved Used an out-dated API version or http instead of https.
400 Invalid Request Input parameters are missing or are not in the correct format.
401 Unauthorized You did not provide credentials / you provided wrong credentials / your license has been deactivated.
402 Payment Required You provided correct credentials, but the license has no request tokens left or is inactive.
429 Too Many Requests You reached the limit of request rate. See above for more details.
500 Internal Server Error Something horrible went wrong. Our engineers get a notification and start working on the issue.
502 Bad Gateway / 503 Service temporarily not available / 504 Gateway Timeout The server is under maintenance. If you see this, retry after a few seconds. Our backend automatically restarts failing servers and we always have some redundancy in place so this should not be a common issue.

Data Formats

Coordinates are always represented as decimal degrees and encoded as JSON numbers. When passed as a list, longitude is always first, followed by latitude. The order in dictionaries (hashes) is undefined.

Strings are encoded as UTF-8. All times are in UTC.

Country codes are in ISO 3166-1 alpha-2

Quota

curl "https://api.aquaplot.com/v1/quota"\
     -u "user:secret"

The above command returns JSON structured like this:

{
    "used": 38,
    "allowed": 1000
}

This endpoint retrieves information on your quota. used indicates how many request tokens have been used today, allowed how many request tokens are available for today. allowed is fixed throughout the day and is reset at 01:30am UTC. allowed_concurrent indicates how many requests you may perform in parallel and features indicates if certain features are available (currently all API licenses have access to all features).

HTTP Request

GET https://api.aquaplot.com/v1/quota

Requires 0 tokens.

HTTP Response

In the current state, this endpoint might return HTTP responses including 402 status codes. This is subject to changes without change of the API version.

Geocode

Retrieve Locations Database

curl "https://api.aquaplot.com/v1/locations" -u "user:secret"

The above command returns JSON structured like this:

[
  {
    "name": "Greater Plutonio",
    "latlng": {
      "lat": -7.833333,
      "lng":12.116667
    },
    "country": "AO",
    "locode":"AOGPO",
    "type":"port"
  },
  {
    "name": "Kuito Terminal",
    "latlng": {
      "lat": -5.433333,
      "lng": 11.483333
    },
    "country": "AO",
    "locode": "AOKOT",
    "type": "port"
  },
]

This endpoint lists all public locations in our database. Your points of interest are not included.

Response JSON

Property Name Description
name String description (usually matches name from UN/LOCODE, World Port Index or other publications).
latlng Coordinates that can be used for further calls to the API. The coordinates are already validated and do not need to be rechecked before calling for example /route.
country Country code in ISO 3166-1 alpha-2 format. Can be an empty string or null if unknown.
locode UN/LOCODE. Can be empty string if not applicable or unknown.
type String description indicating type of location. Currently either one of the following
  • port
  • offshore-installation
  • block

It is not advisable to use this endpoint frequently as the response is rather big in size and does not change often. If you want to provide a search functionality, you can cache the response either on your server or the client, or use our location search endpoint which is much more lightweight.

Search for Locations

curl "https://api.aquaplot.com/v1/locations/hamb"
     -u "user:secret"

The above command returns JSON structured like this:

[
  {
    "name": "Hamburg-Mitte",
    "latlng":{"lat":53.552889,"lng":9.831694},
    "country":"DE",
    "locode":"DEHTJ",
    "type":"port"
  },
  {
    "name":"Hambantota",
    "latlng":{"lat":6.116667,"lng":81.116667},
    "country":"LK",
    "locode":"LKHBA",
    "type":"port"
  },
  {
    "name":"Hamburg",
    "latlng":{"lat":53.552889,"lng":9.831694},
    "country":"DE",
    "locode":"DEHAM",
    "type":"port"
  },
  {
    "name":"Hamburg (Pg) Harbor",
    "latlng":{"lat":-1.623778,"lng":149.958278},
    "country":"PG",
    "locode":"",
    "type":"port"
  },
  {
    "name":"Hamble le Rice",
    "latlng":{"lat":50.852051,"lng":-1.308838},
    "country":null,
    "locode":"",
    "type":"port"
  }
]

This endpoint searches for locations by name or UN/LOCODE. Any match that has the search query as substring will be returned. The search is case-insensitive. Search results are limited to max. 20 results.

HTTP Request

GET https://api.aquaplot.com/v1/locations/<search>

Requires 0 tokens.

URL Parameters

Parameter Description
search Substring of location name or UN/LOCODE

Response JSON

Property Name Description
name String description (usually matches name from UN/LOCODE, World Port Index or other publications).
latlng Coordinates that can be used for further calls to the API. The coordinates are already validated and do not need to be rechecked before calling for example /distance.
country Country code in ISO 3166-1 alpha-2 format. Can be an empty string or null if unknown.
locode UN/LOCODE. Can be empty string if not applicable or unknown.
type String description indicating type of location. Currently either one of the following
  • port
  • offshore-installation
  • block

Get List of ECA Areas

curl "https://api.aquaplot.com/v1/eca" -u "user:secret"

The above command returns JSON structured like this:

{
  "status": "ok",
  "eca_areas": [
    {
      "id": 0,
      "name": "No ECA"
    },
    {
      "id": 1,
      "name": "Caribbean Sea"
    },
    {
      "id": 2,
      "name": "Baltic Sea"
    },
    {
      "id": 3,
      "name": "Hawaiian Islands"
    },
    {
      "id": 4,
      "name": "US East Coast"
    },
    {
      "id": 5,
      "name": "US West Coast"
    },
    {
      "id": 6,
      "name": "North Sea"
    },
    {
      "id": 7,
      "name": "Pearl River Delta"
    },
    {
      "id": 8,
      "name": "Yangtze River Delta"
    },
    {
      "id": 9,
      "name": "Bohai Gulf"
    }
  ]
}

HTTP Request

GET https://api.aquaplot.com/v1/eca

Requires 0 tokens.

Get Coordinates of ECA Areas

curl "https://api.aquaplot.com/v1/eca/all" -u "user:secret"

The above command returns JSON structured like this:

{
  "status": "ok",
  "eca_areas": {
    "ECA:Caribbean_Sea": [
      [
        -67.537222,
        17.310278
      ],
      [
        -67.537222,
        17.310278
      ]
    ],
    "ECA:Baltic_Sea": [
      [
        13.82,
        62
      ],
      [
        13.82,
        62
      ]
    ],
    "ECA:Hawaiian_Islands": [
      [
        -153.009167,
        22.548333
      ],
      [
        -153.009167,
        22.548333
      ]
    ]
  }
}

HTTP Request

GET https://api.aquaplot.com/v1/eca/all

Requires 0 tokens.

Get Coordinates of HRA Area

curl "https://api.aquaplot.com/v1/hra/all" -u "user:secret"

The above command returns JSON structured like this:

{
  "status": "ok",
  "high_risk_areas": {
    "HRA:BMP4_Indian_Ocean_Piracy_Area": [
      [
        65,
        22
      ],
      [
        58,
        22
      ],
      [
        45,
        15
      ],
      [
        39,
        15
      ],
      [
        39,
        -5
      ],
      [
        65,
        -5
      ],
      [
        65,
        22
      ]
    ]
  }
}

HTTP Request

GET https://api.aquaplot.com/v1/hra/all

Requires 0 tokens.

Routing

Calculating Single Route

curl "https://api.aquaplot.com/v1/route\
/from/32.67333984375/33.17434155100208/to/35.92529296875/24.806681353851964" \
  -u "user:secret"

The above command returns geoJSON structured like this:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "total_length": 558.49614719928,
        "seca_length": 0,
        "crossed": [
          "suez-canal"
        ]
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [32.67333984375, 33.174341551002],
          [32.3423, 31.2228],
          [32.310393, 31.094417],
          [32.319995, 30.811504],
          [32.342453, 30.703486],
          [32.305385, 30.568682],
          [32.396751, 30.357018],
          [32.449684, 30.285923],
          [32.500598, 30.260175],
          [32.52428, 30.244705],
          [32.560229, 30.198274],
          [32.585092, 29.973555],
          [32.567552, 29.923606],
          [32.714583, 29.448333],
          [33.237083, 28.553278],
          [34.018333, 27.504556],
          [35.92529296875, 24.806681353852]
        ]
      }
    }
  ]
}

If you post a request with correctly formatted, but invalid coordinates (see validate):

curl "https://api.aquaplot.com/v1/route/from/11.940709/57.703551067/to/13.341178894042969/58.06625598088454"
     -u "user:secret"
{
  "level": 0,
  "message": "invalid request"
}

If you post a request with incorrectly formatted coordinates:

curl "https://api.aquaplot.com/v1/route/from/11.940709/57.703551067/to/13.341178894042969/some_where" \
  -u "user:secret"
{
  "error": "invalid value for to_lat"
}

To prevent a route to cross a canal, you can add a query parameter to the end of your request. The response will contain a route, that avoids declared canals.

curl "https://api.aquaplot.com/v1/route/from/32.67333984375/33.17434155100208/to/35.92529296875/24.806681353851964?suez=false"\
  -u "user:secret"

/route will generate a list of waypoints between two given points. All waypoints are connected by routeable water and represent the shortest path from the two given points, according to our map data. The list starts with the departure coordinate and will end with the destination coordinate. Your inputs will be included in this ist, if they have been valid coordinates. The system will perform minor corrections of the departure and destination coordinates (changes up to ~100m), if they do not point to routeable waters. The returned JSON object contains a property named total_length which is the sum of the lengths of all segments of the way in nautical miles.

Invalid requests will not return a geoJSON object, but a much shortened JSON. Requests are invalid if

  • Coordinates are not represented as JSON numbers (HTTP status 400)
  • Coordinates are missing (HTTP status 404)
  • Departure / destination coordinates are identical (closer than ~1m, HTTP status 500)
  • Departure or / and destination coordinates do not point to routeable water (HTTP status 500)

HTTP Request

GET https://api.aquaplot.com/v1/route/from/<from longitude>/<from latitude>/to/<to longitude>/<to latitude>?suez=true&panama=true

Requires 2 tokens.

URL Parameters

Parameter Description
from longitude JSON number of the longitude of the departure in degrees
from latitude JSON number of the latitude of the departure in degrees
to longitude JSON number of the longitude of the destination in degrees
to latitude JSON number of the latitude of the destination in degrees

Query Parameters

Parameter Required Default Description
suez no true Allow passage of the Suez channel. Possible values: true and false
panama no true Allow passage of the Panama channel. Possible values: true and false
kiel no true Allow passage of the Kiel channel. Possible values: true and false
corinth no false Allow passage of Corinth Canal. Possible values: true and false
gibraltar no true Allow passage of Gibraltar Strait. Possible values: true and false
messina no true Allow passage of Messina Strait. Possible values: true and false
singapore no true Allow passage of Singapore Strait. Possible values: true and false
dover no true Allow passage of Strait of Dover. Possible values: true and false
magellan no true Allow passage of Magellan Strait. Possible values: true and false
floridaStrait no true Allow passage of Strait of Florida. Possible values: true and false
bosphorus no true Allow passage of the Bosphorus. Possible values: true and false
oresund no true Allow passage of the Øresund. Possible values: true and false
northeast no false Allow passage of the Northeast Passage. Possible values: true and false
northwest no false Allow passage of the Northwest Passage. Possible values: true and false
eca no ignore Indication of how to treat ECA areas. Possible values: 'ignore' and 'minimize'
hra no ignore Indication of how to treat HRA area(s). Possible values: 'ignore' and 'minimize'
jwc no ignore Indication of how to treat JWC area(s). Possible values: 'ignore' and 'minimize'
autovalidate no false If set to true, a validation for both start and endpoint will be performed and the validated coordinates will be used as input for the route calculation

Response JSON

The returned json is a geojson object according to RFC7946. The response body holds a feature collection with a single feature. This feature is a line string object with properties, such as total_length, seca_length and crossed.

Property Name Description
total_length Total length of the route in nautical miles
seca_length Length of route which falls into (S)ECA zones in nautical miles
hra_length Length of route which falls into HRA areas in nautical miles
crossed Array of string descriptions of Canals that are crossed, when traveling on the given route
eta Object that includes total travel time as well as a calculated ETA (in UTC) based on the averageVesselSpeedOverGround parameter

Calculating Multiple Routes

curl -H "Content-Type: application/json" \
    -d '{ 
            "requests": [
                {
                    "id": "this-id-will-be-a-property", 
                    "from": {
                        "lat": 0, 
                        "lng": 0
                    }, 
                    "to": {
                        "lat": 1, 
                        "lng": 1
                    } 
                }, 
                { 
                    "id": "b", 
                    "from": {
                        "lat": 0, 
                        "lng": 0
                    }, 
                    "to": {
                        "lat": 43, 
                        "lng": 30
                    },
                    "options": {
                        "suez": "false"
                    }
                }
            ] 
        }' \
    -u "user:secret" \
    https://api.aquaplot.com/v1/routes

The above command returns geoJSON structured like this:

{
  "type": "FeatureCollection",
  "status": "ok",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "total_length": 84.907873,
        "seca_length": 0,
        "eca_area_distances": {
          "0": 84.907873,
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 0,
          "5": 0,
          "6": 0,
          "7": 0,
          "8": 0,
          "9": 0
        },
        "id": "this-id-will-be-a-property"
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            0,
            0
          ],
          [
            1,
            1
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "total_length": 4866.758812,
        "seca_length": 0,
        "eca_area_distances": {
          "0": 4866.758812,
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 0,
          "5": 0,
          "6": 0,
          "7": 0,
          "8": 0,
          "9": 0
        },
        "id": "b"
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            0,
            0
          ],
          [
            -9.151588,
            4.815449
          ],
          [
            -13.191708,
            7.387889
          ],
          [
            -16.350487,
            11.022083
          ],
          [
            -16.515917,
            11.282444
          ],
          [
            -16.975271,
            12.360144
          ],
          [
            -17.675419,
            14.5962
          ],
          [
            -17.291495,
            21.010476
          ],
          [
            -17.248829,
            21.364016
          ],
          [
            -17.197359,
            21.780272
          ],
          [
            -17.180083,
            21.878571
          ],
          [
            -17.170889,
            21.901099
          ],
          [
            -17.032606,
            22.207722
          ],
          [
            -16.176612,
            23.774507
          ],
          [
            -16.12255,
            23.866596
          ],
          [
            -14.650811,
            26.30736
          ],
          [
            -9.410753,
            32.716399
          ],
          [
            -6.176108,
            35.832211
          ],
          [
            -5.93399,
            35.924645
          ],
          [
            -5.693665,
            35.95133
          ],
          [
            -5.368195,
            36.006895
          ],
          [
            -2.096442,
            36.531947
          ],
          [
            -2,
            36.54646
          ],
          [
            -1,
            36.692055
          ],
          [
            0,
            36.828769
          ],
          [
            1,
            36.956651
          ],
          [
            2,
            37.075748
          ],
          [
            3,
            37.186102
          ],
          [
            4,
            37.287754
          ],
          [
            5,
            37.380743
          ],
          [
            6,
            37.465101
          ],
          [
            7,
            37.540861
          ],
          [
            8,
            37.608052
          ],
          [
            8.995056,
            37.666429
          ],
          [
            9.888689,
            37.536105
          ],
          [
            14.702072,
            36.515026
          ],
          [
            14.924977,
            36.49263
          ],
          [
            15.193808,
            36.47216
          ],
          [
            22.891194,
            36.001235
          ],
          [
            23.104583,
            36.001235
          ],
          [
            23.211278,
            36.129583
          ],
          [
            23.445012,
            36.458672
          ],
          [
            24.195328,
            37.606616
          ],
          [
            24.250946,
            37.677843
          ],
          [
            24.335403,
            37.741399
          ],
          [
            24.554443,
            37.865097
          ],
          [
            24.769762,
            38.183119
          ],
          [
            25.940094,
            39.919216
          ],
          [
            26.227112,
            40.042072
          ],
          [
            26.306248,
            40.081749
          ],
          [
            26.383667,
            40.139286
          ],
          [
            26.392593,
            40.197233
          ],
          [
            26.455765,
            40.228694
          ],
          [
            26.582794,
            40.304142
          ],
          [
            26.709137,
            40.395195
          ],
          [
            26.751709,
            40.411143
          ],
          [
            27.475433,
            40.66241
          ],
          [
            27.658768,
            40.695217
          ],
          [
            28.600159,
            40.82628
          ],
          [
            28.9888,
            40.997391
          ],
          [
            28.999443,
            41.020967
          ],
          [
            29.007511,
            41.030161
          ],
          [
            29.035492,
            41.048418
          ],
          [
            29.053001,
            41.073657
          ],
          [
            29.060211,
            41.08388
          ],
          [
            29.062443,
            41.099275
          ],
          [
            29.065361,
            41.105872
          ],
          [
            29.078751,
            41.123073
          ],
          [
            29.067249,
            41.142726
          ],
          [
            29.068451,
            41.16276
          ],
          [
            29.08596,
            41.180334
          ],
          [
            29.124069,
            41.217145
          ],
          [
            30,
            43
          ]
        ]
      }
    }
  ]
}

HTTP Request

POST https://api.aquaplot.com/v1/routes

Requires 1 token for each route.

Body Parameters

The body object must contain a requests key, which holds an array of Request Objects. Currently, a maximum length of 100 is enforced.

Parameter Description
requests Array of Request Objects
Request Objects

Each request object must have a from and a to key and may have an id key and an options key.

Parameter Required Description
from yes A latlng object for the departure location
to yes A latlng object for the destination location
id no A string that is attached to the GeoJSON Feature as a property
averageVesselSpeedOverGround no Average speed over ground in knots that will be used to calculate voyage time and ETA - must be between (including) 1.0 and 100.0 - defaults to 15.0
options no A Route Options object
Route Options
Parameter Default Description
suez true Allow passage of the Suez channel. Possible values: true and false
panama true Allow passage of the Panama channel. Possible values: true and false
kiel true Allow passage of the Kiel channel. Possible values: true and false
corinth false Allow passage of Corinth Canal. Possible values: true and false
gibraltar true Allow passage of Gibraltar Strait. Possible values: true and false
messina true Allow passage of Messina Strait. Possible values: true and false
singapore true Allow passage of Singapore Strait. Possible values: true and false
dover true Allow passage of Strait of Dover. Possible values: true and false
magellan true Allow passage of Magellan Strait. Possible values: true and false
floridaStrait true Allow passage of Strait of Florida. Possible values: true and false
bosphorus true Allow passage of the Bosphorus. Possible values: true and false
oresund true Allow passage of the Øresund. Possible values: true and false
northeast false Allow passage of the Northeast Passage. Possible values: true and false
northwest false Allow passage of the Northwest Passage. Possible values: true and false
eca ignore Indication of how to treat ECA areas. Possible values: 'ignore' and 'minimize'
hra ignore Indication of how to treat HRA area(s). Possible values: 'ignore' and 'minimize'
jwc ignore Indication of how to treat JWC area(s). Possible values: 'ignore' and 'minimize'
nogoBlocks null Custom areas that should be treated as prohibited areas. See Using Custom Nogo Blocks
autovalidate false If set to true, a validation for both start and endpoint will be performed and the validated coordinates will be used as input for the route calculation

Response JSON

The returned json is a geojson object according to RFC7946. The response body holds a feature collection with a single feature for each request. This feature is a line string object with properties, such as total_length, seca_length and crossed.

Property Name Description
id The user specified id provided in the request
total_length Total length of the route in nautical miles
seca_length Length of route which falls into (S)ECA zones in nautical miles
hra_length Length of route which falls into HRA areas in nautical miles
crossed Array of string descriptions of Canals that are crossed, when traveling on the given route
eta Object that includes total travel time as well as a calculated ETA (in UTC) based on the averageVesselSpeedOverGround parameter

Using Custom Nogo Blocks

You can customise the generated route by providing custom nogo areas. nogoBlocks is a parameter supplied to the route options and is an array of objects and where each object contains a coords array of latlngs.

Example

[ 
  { 
    "coords": [
      {
        "lat": 40.979898069620155, 
        "lng": -15.117187500000002
      }, 
      {
        "lat": 45.583289756006316, 
        "lng": -11.25
      },
      …
    ]
  } 
]

Validation of Coordinates

curl "https://api.aquaplot.com/v1/validate/12.34/56.78"
     -u "user:secret"

The above command returns JSON structured like this:

{
  "is_valid": true,
  "suggestion": [
    12.34,
    56.78
  ],
  "normalized": [
    12.34,
    56.78
  ],
  "moved_by": 0
}

If you validated coordinates that are not routeable water, the result looks like this:

{
  "is_valid": false,
  "suggestion": [
    12.2125,
    57.225
  ],
  "normalized": [
    12.555,
    57.28
  ],
  "moved_by": 21490
}

If you validated coordinates that are outside the normal range for longitude, the normalized coordinates will be validated. It is good practice to always use normalized and suggestion for further calls to the API, not your inital input coordinates.

curl "https://api.aquaplot.com/v1/validate/372.34/56.78" 
      -u "user:secret"

For example, above command returns JSON structured like this (notice it's the same as the first):

{ 
  "status": "ok",
  "is_valid": true, 
  "suggestion": [
    12.34, 
    56.78
  ], 
  "normalized": [
    12.340000, 
    56.780000
  ], 
  "moved_by": 0,
  "validatedLatlng": {
    "lat": 56.78,
    "lng": 12.34
  },
  "eca": true,
  "loc": [
    12.34,
    56.78
  ],
  "id": 2,
  "eca_name": "Baltic Sea",
  "timezone_of_validated": "Europe/Stockholm"
}

Using this endpoint, you can check if the coordinates point to routeable water. If the input represents a coordinate on land (or to a lake that is not part of the routeable water in our systems), we return a suggestion that you should use for subsequent requests to /route and /distance along with moved_by which gives you the distance between your input coordinates and our suggestion in meters. If your input points to routable water, the suggestion will contain exactly your input and moved_by will be zero.

HTTP Request

GET https://api.aquaplot.com/v1/validate/<longitude>/<latitude>

Requires 0 tokens.

URL Parameters

Parameter Description
longitude JSON number of the longitude in degrees
latitude JSON number of the latitude in degrees

Response JSON

Property Name Description
is_valid Boolean value indicating whether the normalized input can be used for /distance and /route calls
suggestion Suggested location to be used for further calls to the API. Same as the normalized input if in routeable water
normalized Input location normalized such that longitude is within [-180, 180]
moved_by Distance between normalized and suggestion in meters
validatedLatlng Convenience: Suggested location in latlng format
eca Boolean indicating if location is inside ECA area
eca_name Name of ECA area ('No ECA' if outside)
timezoneofvalidated Timezone identifier for validated location

Validation of Multiple Coordinates

You can also combine multiple validate requests for bulk validation.

HTTP Request

POST https://api.aquaplot.com/v1/validate

Requires 0 tokens.

curl -H "Content-Type: application/json"\
     -d '{"requests":[{ "lat": 0, "lng": 0 }, { "lat": 1, "lng": 1 }]}'\
     -u "user:secret"\
      https://api.aquaplot.com/v1/validate

The response contains an array of objects structured identically to the response from a single validation.

The above command returns JSON structured like this:

[
  {
    "status": "ok",
    "is_valid": true,
    "suggestion": [0,0],
    "normalized": [0,0],
    "moved_by": 0,
    "validatedLatlng": {
      "lat": 0,
      "lng":0
    },
    "loc": [0,0],
    "eca": false, 
    "eca_name": "No ECA",
    "timezone_of_validated": "Etc/GMT"
  },
  ...
]

AIS

Get Latest AIS For Single Vessel

curl "https://api.aquaplot.com/v1/vessels/mmsi/123456789/latest"
     -u "user:secret"

#     or alternatively

curl "https://api.aquaplot.com/v1/vessels/imo/1234567/latest"
     -u "user:secret"

The above command returns JSON structured like this:

{
  "status": "ok", 
  "vessel": {
    "mmsi": "123456789", 
    "imo": "1234567", 
    "name": "SOME VESSEL NAME",
    "callsign": "ABCD1", 
    "flag": "Norway", 
    "type": "Other", 
    "max_draught": "6.2"
  }, 
  "current": {
    "navigational_status": "Restricted maneuverability", 
    "speed_over_ground": "6.4", 
    "course_over_ground": "78.7", 
    "true_heading": "78", 
    "cargo_type": "Hazard or Pollutant Category X", 
    "activity": "Towing", 
    "destination": "WEST OF SVALBARD", 
    "estimated_time_of_arrival": "2018-10-01T15:00:00.000Z"
  }, 
  "latlng": {
    "lat": 78.07095833333334, 
    "lng": 9.061568333333334
  }, 
  "signal_timestamp": "2018-10-02T04:16:43.000Z"
}

This endpoint will forcefully trigger an AIS data retrieval and return a vessels latest position.

HTTP Request

GET https://api.aquaplot.com/v1/vessels/mmsi/<mmsi>/latest
GET https://api.aquaplot.com/v1/vessels/imo/<imo>/latest

Requires 1 token.

URL Parameters

Parameter Description
mmsi MMSI identifier of vessel of interest.
imo IMO identifier of vessel of interest.

Response JSON

Property Name Description
status String describing if call was successful (either "ok" or "error"). If "ok", properties mmsi, name, latlng and signal_timestamp will be present in the response.
message Only present if status equals "error".
mmsi MMSI identifier that was used as url_parameter.
name Vessel name if known. Can be an empty string.
latlng Reveived coordinates of vessel at time signal_timestamp.
signal_timestamp Time that AIS signal was received in UTC.

Get Latest AIS For Multiple Vessels

This endpoint let's you get the same AIS data for multiple vessels (up to 100) at the same time.

curl -H "Content-Type: application/json"\
     -d '{"mmsiNumbers":["123456789","987654321"]}'\
     -u "user:secret"\
      https://api.aquaplot.com/v1/vessels/latest

The above command returns JSON structured like this:

[
  {
    "status": "ok", 
    "vessel": {
      "mmsi": "123456789", 
      "imo": "1234567", 
      "name": "SOME VESSEL NAME",
      "callsign": "ABCD1", 
      "flag": "Norway", 
      "type": "Other", 
      "max_draught": "6.2"
    }, 
    "current": {
      "navigational_status": "Restricted maneuverability", 
      "speed_over_ground": "6.4", 
      "course_over_ground": "78.7", 
      "true_heading": "78", 
      "cargo_type": "Hazard or Pollutant Category X", 
      "activity": "Towing", 
      "destination": "WEST OF SVALBARD", 
      "estimated_time_of_arrival": "2018-10-01T15:00:00.000Z"
    }, 
    "latlng": {
      "lat": 78.07095833333334, 
      "lng": 9.061568333333334
    }, 
    "signal_timestamp": "2018-10-02T04:16:43.000Z"
  },
  {
    "status": "ok", 
    "vessel": {
      "mmsi": "987654321", 
      "imo": "7654321", 
      "name": "OTHER VESSEL NAME",
      "callsign": "ABCDE", 
      "flag": "Norway", 
      "type": "Other", 
      "max_draught": "6.2"
    }, 
    "current": {
      "navigational_status": "Restricted maneuverability", 
      "speed_over_ground": "6.4", 
      "course_over_ground": "78.7", 
      "true_heading": "78", 
      "cargo_type": "Hazard or Pollutant Category X", 
      "activity": "Towing", 
      "destination": "WEST OF SVALBARD", 
      "estimated_time_of_arrival": "2018-10-01T15:00:00.000Z"
    }, 
    "latlng": {
      "lat": 78.07095833333334, 
      "lng": 9.061568333333334
    }, 
    "signal_timestamp": "2018-10-02T04:16:43.000Z"
  }
]

HTTP Request

POST https://api.aquaplot.com/v1/vessels/latest

Requires 1 token for each vessel.

Body Parameters

The body object must contain a mmsiNumbers key, which holds an array of MMSI identifiers. Currently, a maximum length of 100 is enforced.

Parameter Description
mmsiNumbers Array of MMSI identifiers

Response JSON

The call returns an array, where each item in the array is formatted identical to the response format from the Single Vessel call.