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/search/{querystring}	Get the most current static ship information for ship(s) matching a query string
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/search/{querystring}	Get the most current static ship information for ship(s) matching a query string
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[]: TrackResult

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

PortExtended

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

Port

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

POST /ship/area

Tags: EXPERIMENTAL, ship

Area and Timestamp.

AreaPost

application/json

202 Accepted: successful operation. The operation is executing.

JobId

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

ShipListResponse
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.

Ship.

ShipHistoricalPost

application/json

200 OK: successful operation

PortHistorical

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

ShipHistoricalResult
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.

ShipHistoricalPost

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.

Ship.

ShipHistoricalPost

application/json

200 OK: successful operation

TripHistorical

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

rot: integer (int32)

Rate of Turn as indicated by the AIS message -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[]: Ship

Add a new ship to the ship register.

POST /ship/register

Tags: EXPERIMENTAL, ship

Add a new ship to the ship register.

Ship.

Ship

application/json

200 OK: successful operation

ShipId

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[]: Ship

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[]: Ship

Update a new ship in the ship register.

PUT /ship/register/{mmsi}

Tags: EXPERIMENTAL, ship

Static ship information.

Ship


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

application/json

200 OK: successful operation

ShipId

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 formatted 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'.

RoutePost

application/json

202 Accepted: successful operation. The operation is executing.

JobId

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'.

RoutePost

application/json

200 OK: successful operation

RouteResponse

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

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

Get the most current static ship information for ship(s) matching a query string

GET /ship/search/{querystring}

Tags: EXPERIMENTAL, ship


querystring	Query string to match MMSI/IMO/name/callsign for the ship.	path	string

application/json

200 OK

successful operation

records: object[]

object

mmsi: integer (int32)

219019139

imo: integer (int32)

name: string

"MARSTAL MAERSK"

callsign: string

"OWJK2"

position: GeoJson

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

GET /ship/select

Tags: EXPERIMENTAL, ship

application/json

200 OK

successful operation

records: object[]: SelectShip

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

POST /ship/select

Tags: EXPERIMENTAL, ship

Ship.

SelectShip

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[]: SelectShip

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[]: TrackResult

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.

TrackPost

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

StandardResponse

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

TrackResult

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.

TrackPut


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.

Warp

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/

{
    "coordinates": [
        [
            [
                10.1,
                55.2
            ],
            [
                10.3,
                55.1
            ],
            [
                10.2,
                55.2
            ]
        ]
    ],
    "type": "Polygon"
}

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)

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)

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[]

Quay

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[]: Bollard

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

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)

name: string

"MARSTAL MAERSK"

callsign: string

"OWJK2"

length: integer (int32)

width: integer (int32)

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.

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[]: ShipListItem

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[]

GeoJson

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[]: Port

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