GateHouse AIS REST interface

Base URL: /api/portserver, Version: 0.2.1

AIS system for monitoring vessel traffic

Schemes: https, http

Summary

Tag: EXPERIMENTAL

This call may change without warning.

Operation Description
POST /ship/route

Start route calculation from source to destination.

GET /ship/route/{id}

Query / poll result by identifier

POST /ship/route/execute

Perform route calculation in one operation

POST /ship/historical/port

Get a list of last visited ports for the given ship.

POST /ship/historical/trip

Get a list of last trips for the given ship.

POST /ship/historical/track

Get a historical track for the given ship for the given period.

GET /ship/historical/track
POST /ship/info

Return the static information for the given ship for the given time.

GET /ship/info/{mmsi}

Get the most current static ship information for a specific ship

GET /ship/position/{mmsi}

Get the most current position for a specific ship

POST /ship/register

Add a new ship to the ship register.

GET /ship/register

Get static ship information for all ships from the ship register

PUT /ship/register/{mmsi}

Update a new ship in the ship register.

GET /ship/register/{mmsi}

Get static ship information for a specific ship from the ship register

DELETE /ship/register/{mmsi}

Get status of arrivals for all ships towards a port

POST /ship/select

Select a ship for display pan/zoom for a user in aisWeb.

GET /ship/select

Get selected ships for pan/zoom for this calling user.

GET /ship/select/{owner}

Get selected ships for pan/zoom for this calling user for the supplied owner.

POST /ship/area

Return a list of ships in given area at a given point in time.

GET /ship/area/{id}

Query / poll result by identifier

Tag: PRODUCTION

This call will only change in a release.

Operation Description
POST /ship/track

Start a track of a ship towards a predefined destination

GET /ship/track

Get status of a track for all ships towards predefined destinations

PUT /ship/track/{id}

Update arrival with ERP information

GET /ship/track/{id}

Get status of a track of a ship towards a predefined destination

DELETE /ship/track/{id}

Stop and delete a track.

GET /port/list

Search for a port or list all ports

GET /port/info/{id}

Get extented port information

GET /port/arrivals/{id}

Get status of arrivals for all ships towards a port

Tag: route

Calculate ship route

Operation Description
POST /ship/route

Start route calculation from source to destination.

GET /ship/route/{id}

Query / poll result by identifier

POST /ship/route/execute

Perform route calculation in one operation

Tag: track

Track ship to destination

Operation Description
POST /ship/track

Start a track of a ship towards a predefined destination

GET /ship/track

Get status of a track for all ships towards predefined destinations

PUT /ship/track/{id}

Update arrival with ERP information

GET /ship/track/{id}

Get status of a track of a ship towards a predefined destination

DELETE /ship/track/{id}

Stop and delete a track.

Tag: port

Port information

Operation Description
GET /port/list

Search for a port or list all ports

GET /port/info/{id}

Get extented port information

GET /port/arrivals/{id}

Get status of arrivals for all ships towards a port

DELETE /ship/register/{mmsi}

Get status of arrivals for all ships towards a port

Tag: ship

Ship information

Operation Description
POST /ship/historical/port

Get a list of last visited ports for the given ship.

POST /ship/historical/trip

Get a list of last trips for the given ship.

POST /ship/historical/track

Get a historical track for the given ship for the given period.

GET /ship/historical/track
POST /ship/info

Return the static information for the given ship for the given time.

GET /ship/info/{mmsi}

Get the most current static ship information for a specific ship

GET /ship/position/{mmsi}

Get the most current position for a specific ship

POST /ship/register

Add a new ship to the ship register.

GET /ship/register

Get static ship information for all ships from the ship register

PUT /ship/register/{mmsi}

Update a new ship in the ship register.

GET /ship/register/{mmsi}

Get static ship information for a specific ship from the ship register

POST /ship/select

Select a ship for display pan/zoom for a user in aisWeb.

GET /ship/select

Get selected ships for pan/zoom for this calling user.

GET /ship/select/{owner}

Get selected ships for pan/zoom for this calling user for the supplied owner.

POST /ship/area

Return a list of ships in given area at a given point in time.

GET /ship/area/{id}

Query / poll result by identifier

Security

basic_authentication

Type: basic

Paths

Get status of arrivals for all ships towards a port

GET /port/arrivals/{id}

Tags: PRODUCTION, port

Get the current status of the tracks of the ships towards the destination. Returns the ETA.

id

id of the port

path integer

application/json

200 OK

successful operation

records: object[]
Get extented port information

GET /port/info/{id}

Tags: PRODUCTION, port

Get extented port information

id

id of the port

path integer

application/json

200 OK

successful operation

Search for a port or list all ports

GET /port/list

Tags: PRODUCTION, port

Get a list of ports based on a search pattern

pattern

Simple search pattern based on port name. Use * for wildcard. Default all

query string
offset

Use for pagination. Start index of ports returned.

query integer
limit

Use for pagination. Limit the number of ports returned.

query integer 10000

application/json

200 OK

successful operation

Return a list of ships in given area at a given point in time.

POST /ship/area

Tags: EXPERIMENTAL, ship

.

Area and Timestamp.

application/json

202 Accepted

successful operation. The operation is executing.

Query / poll result by identifier

GET /ship/area/{id}

Tags: EXPERIMENTAL, ship

Once the job has been completed (or aborted) and result given back the job is deleted. The operation will timeout if not completed in two minutes.

id

Identifier returned from the /ship/area POST call. Notice this is a 64 bit value.

path integer (int64)

application/json

200 OK

successful operation

202 Accepted

The operation is still executing. call again in a while. Recommended wait 5-10 seconds.

Get a list of last visited ports for the given ship.

POST /ship/historical/port

Tags: EXPERIMENTAL, ship

Get a list of last visited ports for the given ship.

application/json

200 OK

successful operation

GET /ship/historical/track

Tags: EXPERIMENTAL, ship

Get a historical track for the given ship for the given period between begin and end. Resolution of the track indicates the interval between samples returned.

application/json

200 OK

successful operation

202 Accepted

Accepted for processing. The job has been started but is not yet completed. Try again in a minute or so.

Get a historical track for the given ship for the given period.

POST /ship/historical/track

Tags: EXPERIMENTAL, ship

Get a historical track for the given ship for the given period between begin and end. Resolution of the track indicates the interval between samples returned.

Ship identity.

application/json

202 Accepted

Accepted for processing. The job has been started but is not yet completed. Call the accompanying GET to retrieve the result.

Get a list of last trips for the given ship.

POST /ship/historical/trip

Tags: EXPERIMENTAL, ship

Get a list of last trips for the given ship.

application/json

200 OK

successful operation

Return the static information for the given ship for the given time.

POST /ship/info

Tags: EXPERIMENTAL, ship

.

Ship.

time: string (date-time)
"2016-08-17T12:34:56Z"
ship: Ship

application/json

200 OK

successful operation

ship: Ship
Get the most current static ship information for a specific ship

GET /ship/info/{mmsi}

Tags: EXPERIMENTAL, ship
mmsi

MMSI or IMO for the ship.

path integer

application/json

200 OK

successful operation

ship: Ship
Get the most current position for a specific ship

GET /ship/position/{mmsi}

Tags: EXPERIMENTAL, ship
mmsi

MMSI or IMO for the ship.

path integer

application/json

200 OK

successful operation

position: GeoJson
ship: object
mmsi: integer (int32)
219345000
navstatus: integer

Navigational status as indicated by the AIS information.

heading: integer (int32)

Heading in degrees 0..359

180
rot: integer (int32)

Rate of Turn as indicated by the AIS message -127..127

127
Get static ship information for all ships from the ship register

GET /ship/register

Tags: EXPERIMENTAL, ship

application/json

200 OK

successful operation

records: object[]
Add a new ship to the ship register.

POST /ship/register

Tags: EXPERIMENTAL, ship

Add a new ship to the ship register.

Ship.

application/json

200 OK

successful operation

Get status of arrivals for all ships towards a port

DELETE /ship/register/{mmsi}

Tags: EXPERIMENTAL, port

Get the current status of the tracks of the ships towards the destination. Returns the ETA.

mmsi

MMSI for the ship. Notice this may be a 64 bit integer.

path integer

application/json

200 OK

successful operation

records: object[]
Get static ship information for a specific ship from the ship register

GET /ship/register/{mmsi}

Tags: EXPERIMENTAL, ship
mmsi

MMSI for the ship. Notice this may be a 64 bit integer.

path integer

application/json

200 OK

successful operation

records: object[]
Update a new ship in the ship register.

PUT /ship/register/{mmsi}

Tags: EXPERIMENTAL, ship

Static ship information.

mmsi

MMSI for the ship. Notice this may be a 64 bit integer.

path integer

application/json

200 OK

successful operation

Start route calculation from source to destination.

POST /ship/route

Tags: EXPERIMENTAL, route

Start route calculation from 'source' to 'destination'. A route is calculated (if possible) and a set of waypoint positions are returned. The 'source' and 'destination' parameters must each define either a 'port', 'ship' or 'position'. The 'port' can be either a 'port id' or a 'port locode' or a 'port name'. A ship can be one or more of a MMSI, IMO number, shipname or callsign. A 'position' is a GEOJSON formatet point. If a ship is used then the draught of the ship is used in the calculations (if available). The draught can be overridden by applying a draught parameter in the 'source'. The function returns an identifier. Subsequently call /route/result using the identifier to obtain the result.

Object defining 'source' and 'destination'.

application/json

202 Accepted

successful operation. The operation is executing.

Perform route calculation in one operation

POST /ship/route/execute

Tags: EXPERIMENTAL, route

Perform route calculation. This function combines /route/start and polling /route/result until completed. The function will thus block for the duration of the route calculation, which can be a couple of minutes.

Object defining 'source' and 'destination'.

application/json

200 OK

successful operation

Query / poll result by identifier

GET /ship/route/{id}

Tags: EXPERIMENTAL, route

Once the job has been completed (or aborted) and result given back the job is deleted. The operation will timeout if not completed in two minutes.

id

Route calculation identifier. Notice this is a 64 bit value

path integer (int64)

application/json

200 OK

successful operation

202 Accepted

The operation is still executing. call again in a while. Recommended wait 5-10 seconds.

Get selected ships for pan/zoom for this calling user.

GET /ship/select

Tags: EXPERIMENTAL, ship

application/json

200 OK

successful operation

records: object[]
Select a ship for display pan/zoom for a user in aisWeb.

POST /ship/select

Tags: EXPERIMENTAL, ship

Ship.

application/json

200 OK

successful operation

Get selected ships for pan/zoom for this calling user for the supplied owner.

GET /ship/select/{owner}

Tags: EXPERIMENTAL, ship
owner

Filter for only message from owner.

path string

application/json

200 OK

successful operation

records: object[]
Get status of a track for all ships towards predefined destinations

GET /ship/track

Tags: PRODUCTION, track

Get the current status of the track of all ship towards the destinations. Return the current track and ETA. Use this to get all active tracks. Call /ship/track/{ID} DELETE to stop and delete the track.

application/json

200 OK

successful operation

records: object[]
Start a track of a ship towards a predefined destination

POST /ship/track

Tags: PRODUCTION, track

Start a track of a ship towards a predefined destination. Perform an initial route calculation. Will then keep track of the ship until it has reached its destination. By polling /ship/track/{ID} GET the current status can be retrieved. Call /ship/track/{ID} DELETE to stop and delete the track.
If the ship cannot be found then an error code is returned unless "source.ship.create" = true.

Object defining 'source' and 'destination'. Normally source should reference a ship and destination should reference a port or a position.

application/json

200 OK

successful operation

Stop and delete a track.

DELETE /ship/track/{id}

Tags: PRODUCTION, track

Stop and delete a track.

id

id of the track

path integer (int64)

application/json

200 OK

successful operation

Get status of a track of a ship towards a predefined destination

GET /ship/track/{id}

Tags: PRODUCTION, track

Get the current status of the track of the ship towards the destination. Return the current track and ETA. Call /track/{ID} DELETE to stop and delete the track.

id

id of the track

path integer (int64)

application/json

200 OK

successful operation

Update arrival with ERP information

PUT /ship/track/{id}

Tags: PRODUCTION, track

Update the ERP information for the arrival with any information available from the ERP system.

id

id of the track

path integer (int64)

application/json

200 OK

successful operation

Schema definitions

AreaPost: object

time: string (date-Time)

Point in time from when to extract the data. Default is now. NB!! Currently not used as only now is supported.

"2017-10-15T12:00:00Z"
timeout: string (date-Time)

Duration back in time to show ships. Defaults to 24 hours = 24:00:00

"24:00:00"
polygon: Polygon

Bollard: object

Bollard. Consists of a numbered identifier and a position.

id: integer
position: GeoJson

Destination: object

port: Port
ship: Ship
position: GeoJson
location: Location
eta: string (date-Time)

For input: Expected Time of Arrival as indicated in eg. ERP system. Can be used for reference. For output: Expected Time of Arrival as calculated.

"2016-01-15T12:00:00Z"

ERP: object

The erp object is used for storing information relevant to the ERP system. It can contain any kind of valid json information. Only the shown properties are recognized by the AIS system.

warp: object[]

The warp array is used for describing upcoming warps. The first is arrival at the port and any subsequent are movements internally at the port. Notice the eta of the first warp is used by the AIS system as indication of the expected arrival time at the port.

attributes: object[]

The attributes may be used as a key:value set that can be displayed and edited in aisWeb. The information is entirely up the port and integrator.

"[{\"key\" : \"Last visit\", \"value\" : \"2016-01-04T12:00:00Z\", \"datatype\" : \"datetime\", \"edit\" : false}, {\"key\" : \"Garbage collected\", \"value\" : false, \"datatype\" : \"boolean\", \"edit\" : true}]"
ErpAttributes
waypoints: object[]

Defining one or more waypoints, the portserver will interpret the defined points as "sub destinations", which means that the colculated route will pass through the points toward the final destination. When waypoints are defined the track result will contain an array of waypoint ETAs that will map to the defined list of waypoints.

"[{\"position\": { \"coordinates\": [10.69979572296143,57.80120849609375],\"type\": \"Point\"}}]"
ErpWaypoint

ErpAttributes: object

Optional attributes shown in the aisWeb display. The fields are purely informational and the contents is not used by aisWeb.

key: string
value: string

Type is string by default, but can also be a boolean or a number

datatype: string

string, boolean, number, datetime and enum. Default is string

edit: boolean

Indicates whether the ERP system can accept external changes. I.e. field should be editable in aisWeb

editKey: boolean

Indicates whether the key field should be editable in aisWeb

ErpWaypoint: object

position: GeoJson
port: Port
location: Location

GeoJson: object

Object containing a position, linestring (track) or polygon. Based on http://geojson.org/ and https://github.com/dret/GeoJSON-X. Extensions defined are time (timestamp in ISO format, cog (Course Over Ground in degrees 0..360), sog (Speed Over Ground in knots). Please notice extensions in coordinates can be both numbers and string (time)

"Position: {\"type\": \"Point\", \"extensions\": [\"time\", \"cog\", \"sog\"], \"coordinates\": [10.1, 55.2, \"2016-01-15T12:00:00Z\", 120.1, 8.4]\"}, Track: {\"type\": \"LineString\", \"extensions\": [\"time\", \"cog\", \"sog\"],  \"coordinates\": [ [10.1, 55.2, \"2016-01-15T12:00:00Z\", 120.1, 8.4] [10.3, 55.1, \"2016-01-15T12:30:00Z\", 118.2, 8.3]]\"}"
extensions: string[]
string
coordinates: number[]
number
type: string , x ∈ { Point , MultiPoint , LineString , MultiLineString , Polygon , MultiPolygon , GeometryCollection }

JobId: object

id: integer (int64)

Location: object

A location or shape. The location should at least contain a position but can also contain one or more polygons or a combination of these. The first object (position or polygon) is the arrived destination. The second (optional) is the arriving area around the destination. The third (optional) is the departed area.

position: GeoJson
name: string
"BAYONNE"
id: string (uuid)

Polygon: object

GeoJSON object containing a polygon. Based on http://geojson.org/

"{\"type\":\"Polygon\",  \"coordinates\":[[[10.1, 55.2], [10.3, 55.1], [10.2, 55.2]]]} "
extensions: string[]
string
coordinates: number[]
number
type: string , x ∈ { Polygon }

Port: object

As input parameter, either id or locode or name can be used. Notice that id and locode is unique whereas name may not be unique. The Locode is not defined for all ports.

id: integer (int64)
7790
locode: string

5 alphanumeric characters: 2 for country and 3 for location. Notice that the Locode is not defined for all ports.

"USBAY"
name: string
"BAYONNE"

PortExtended: object

Extended port information. Notice that id and locode is unique whereas name may not be unique. The Locode is not defined for all ports. shapes is a set of GeoJSON objects that should be drawn on a map of the port

id: integer (int64)
7790
locode: string

5 alphanumeric characters: 2 for country and 3 for location. Notice that the Locode is not defined for all ports.

"USBAY"
name: string
"BAYONNE"
position: GeoJson
shapes: GeoJson
quay: object[]

PortHistorical: object

Identification of port and arrival "ata" and departure "atd" time

ata: string (date-time)

Actual Time of Arrival [UTC]

atd: string (date-time)

Actual Time of Departure [UTC]

port: Port

Position-X: object

GeoJSON object containing a position along with a timestamp and optionally "cog", "sog". Based on http://geojson.org/ and https://github.com/dret/GeoJSON-X. Extensions defined are time (timestamp in ISO format, cog (Course Over Ground in degrees 0..360), sog (Speed Over Ground in knots). Please notice extensions in coordinates can be both numbers and string (time)

"{\"type\":\"Point\", \"extensions\" : [\"time\", \"cog\", \"sog\"],  \"coordinates\":[10.1, 55.2, \"2016-01-15T12:00:00Z\", 120.1, 8.4]\"}"
extensions: string[]
string
coordinates: number[]
number
type: string , x ∈ { Point }

Quay: object

A quay area defined by a name a linestring or polyline in GeoJSON and a polygon

id: integer
name: string
line: GeoJson
polygon: GeoJson
bollards: object[]

RoutePost: object

source: Source
destination: Destination

RouteResponse: object

id: integer (int64)
length: integer (int64)

Length / distance of the track [m].

ship: object

Notice not all parameters are always set. And you will only get this if a ship is used as input.

eta: string (date-time)

Timestamp of expected arrival time at destination. This is based

bs_ts: string (date-time)

Timestamp of last received position

sog: number

Speed Over Ground of last received position

route: GeoJson

SelectShip: object

One or more ships used for selection in aisWeb.

username: string
owner: string
ship: object[]

Ship: object

Static information to identify a ship. To query a given ship provide any information available. Using more information will enhance the chance for identification.

mmsi: integer (int32)
219019139
imo: integer (int32)
9619971
name: string
"MARSTAL MAERSK"
callsign: string
"OWJK2"
length: integer (int32)
140
width: integer (int32)
22
draught: number

Draught of the ship [m]. Notice this info may change for each voyage.

8.7
grt: integer (int32)

Displacement of the ship. Notice this info is not available in the AIS information.

10000
create: boolean

If true the system will create an entry with this ship if it cannot find any information on the ship. This can be useful for ships without an AIS transponder.

eta: string (date-Time)

Expected Time of Arrival as indicated in the AIS message.

"2016-01-15T12:00:00"
destination: string

Destination as indicated in the AIS message.

"MELBOURNE"
country: string

United Nations Country name. See http://www.unece.org/cefact/locode/service/location.

"France"
shiptype: string

Textual description of ship type. Based on the AIS information. May also include cargo

"TANKER"

ShipHistoricalPost: object

begin: Start time for the track [UTC] default yesterday midnight, end: End time for the track [UTC] default last midnight.

ship: Ship
begin: string (date-time)

Start timestamp for the track. Always UTC

"2015-06-17T12:34:56Z"
end: string (date-time)

End timestamp for the track. Always UTC

"2015-06-17T12:34:56Z"
resolution: string (time)

Resolution of the track. Time between samples as hh:mm:ss

"00:10:00"

ShipHistoricalResult: object

ship: Ship
track: GeoJson

ShipId: object

mmsi: integer (int64)

ShipListItem: object

Description of a ship in a ship list. Contains static and dynamic information.

ship: Ship
position: Position-X

ShipListResponse: object

Zero or more ships found inside the area.

records: object[]

Source: object

draught: number

Use this to override the draught of the ship [m] for the route calculation. Deprecated, use ship.draught instead

8.7
port: Port
ship: Ship
position: GeoJson

StandardResponse: object

message: string

TrackPost: object

source: Source
destination: Destination
erp: ERP

TrackPut: object

ERP information in JSON format. Notice not all parameters are always set

id: integer (int64)
erp: ERP

TrackResult: object

Notice not all parameters are always set. route: Linestring indicating the automatic route calculated. Notice presence of this field is dependent on system configuration and user access rights. geo: Polygon showing the expected arrival of the ship in the port.

id: integer (int64)
code: integer

A status code indicating the current tracking status. https://maritime.gatehouse.dk/pub/api-doc/portserver/

route: GeoJson
eta: string (date-time)

Estimated Time of Arrival (ETA) in ISO Extended format

"2015-06-17T12:34:56Z"
sog: number
geo: object[]
erp: ERP
source: Source
destination: Destination

TripHistorical: object

The port array will contain 2 entries: departure and destination port. Notice the departure and arrival port may be the same port. atd is the departure time and ata is the arrival time.

atd: string (date-time)

Actual Time of Departure [UTC]

ata: string (date-time)

Actual Time of Arrival [UTC]

port: object[]

Warp: object

Any information can be stored and retrieved. The parts used in the system are shown here.

id: integer

Optional identifier assigned by the ERP system

quay: object[]
object
name: string
bollards: integer[]
integer
eta: string (date-time)

Estimated Time of Arrival (ETA) in ISO Extended format

"2015-06-17T12:34:56Z"
etd: string (date-time)

Estimated Time of Departure (ETD) in ISO Extended format

"2015-06-17T12:34:56Z"
starboard: boolean

Optional indication of intended side to the berth. true = starboard, false = port and N/A = unknown

color: string

Color for arrival in hex format e.g. #00ff88

 

Generated on 2020-05-06T10:53:11+02:00