API

Introduction

This MIS Online provides an API that allows developers to interact with system data from their own applications. The API can either be accessed by SOAP or REST.

The REST API allows for HTTP GET and POST access to the MIS Online and is available using the usage URL's specified in the methods below. If you are using the REST API from .NET, there is a MISOnline Library DLL available (download) which allows you to de-serialize the XML to strongly defined types, making them easier to work with. Not all functionality is exposed via the REST API.

The SOAP API allows for SOAP acccess to the MIS Online and is available by connecting to api.asmx. The WSDL is availably using here which describes the definition of the objects required to use the SOAP API - as such it is not necessary to use the MISOnline Library.

API Key

Each developer wanting to use the MIS Online API requires an API Key. This key is used to authenticate the developer application and track access levels. Excessive levels of requests on the API will result in an API Key being deactivated. It is important that the developer keeps their API Key secure so that it is not misused and result in deactivation.

Requests for API Keys should be made through the HHA ticket system located at http://hha.zendesk.com. Please note that requests are only accepted with an operational justification.

Methods

GetAnchored

Returns a Visits object representing all the vessels that are currently anchored.

SOAP Usage: GetAnchored([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getanchored.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetAreasAnchorages

Returns a AreaLines object representing all the anchorages in the database.

SOAP Usage: GetAreasAnchorages([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
GetAreasBerths

Returns a AreaLines object representing all the berths in the database.

SOAP Usage: GetAreasAnchorages([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
GetAreasExternalPorts

Returns a AreaLines object representing all the external ports in the database.

SOAP Usage: GetAreasAnchorages([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
GetArrivals

Returns a Visits object representing all the vessels that are in transit into the harbour.

SOAP Usage: GetArrivals([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getarrivals.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetBerthed

Returns a Visits object representing all the vessels that are berthed in the harbour.

SOAP Usage: GetBerthed([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getberthed.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetDepartures

Returns a Visits object representing all the vessels that are in transit out of the harbour.

SOAP Usage: GetDepartures([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getdepartures.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetForecasts

Returns a Visits object representing all the vessels that forecast to arrive into the harbour.

SOAP Usage: GetForecasts([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getforecasts.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetLiveSensors

Returns a Sensors object representing all the live sensors and their associated values over the previous 24 hours.

SOAP Usage: GetLiveSensors([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getlivesensors.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetPredictedHighLowTide

Returns a Tide object representing the next high and low tide values and times.

SOAP Usage: GetPredictedHighLowTide([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getpredictedhighlowtide.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetPredictedSensors

Returns a Sensors object representing all the prediction sensors and their associated values over the previous 14 days and 14 days into the future.

SOAP Usage: GetPredictedSensors([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getpredictedsensors.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetShifts

Returns a Visits object representing all the vessels that are shifting in the harbour.

SOAP Usage: GetShifts([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getshifts.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetTransits

Returns a Visits object representing all the vessels that are transiting in the harbour.

SOAP Usage: GetTransits([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/gettransits.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
IsLiveSensorOld

Returns a boolean representing whether the data feed is out of date.

SOAP Usage: IsLiveSensorOld()

IsPredictedSensorOld

Returns a boolean representing whether the data feed is out of date.

SOAP Usage: IsPredictedSensorOld()

IsTrafficOld

Returns a boolean representing whether the data feed is out of date.

SOAP Usage: IsTrafficOld()

SetForecast

Creates or updates a queued forecast and returns an ApiResult objects representing whether the action was successful.

SOAP Usage: SetForecast([API Key], [Forecast])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • [Forecast] (Forecast) represents a forecast object to be created/updated. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with an ApiResult Description of "Forecast cannot be null", "UniqueIdentifier cannot be empty.", "UniqueIdentifier can not contain any of the following characters: \ / : ? " < > |", "ArrivalPort cannot be empty.", "The unique identifier has already been used by someone else.", "ETA cannot be null.", "ETA must be set.", "VesselName cannot be empty." or "Unable to add forecast to the queue." if there's a problem with the input.

REST Usage: api/setforecast?key=[API Key]&uniqueidentifier=[Unique Identifier]&vesselname=[Vessel Name]&vessellloydsnumber=[Vessel Lloyds Number]&vesseldraught=[Vessel Draft]&eta=[ETA]&lastport=[Last Port]&arrivalport=[Arrival Port]&personsonboard=[Persons On Board]&hazardousonboard=[Hazardous On Board]&billingAgent=[Billing Agent]&cancel=[Cancel]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • [Unique Identifier] (string) represents a value that is unique for each forecast which can then be used to provide updates to forecasts. Required.
  • [Vessel Name] (string) represents the name of the vessel forecast to arrive in the harbour. Required.
  • [Vessel Lloyds Number](string) represents the Lloyds number of the vessel forecast to arrive in the harbour. This is only optional when [Vessel Name] is provided.
  • [Vessel Draught] (decimal) represents the expected draft of the vessel on arrival. Optional.
  • [ETA] (string) represents the estimated date and time of the vessels arrival. This string must conform to ISO 8601 (2008-11-01T19:35:00.0000000Z) or RFC 1123 (Sat, 01 Nov 2008 19:35:00 GMT). Required.
  • [Last Port] (string) represents the name or UN/LOCODE of the last port the vessel called at before expected arrival. Optional.
  • [Arrival Port] (string) represents the name or UN/LOCODE of the port within the harbour the vessel is expected to call at. Required.
  • [Persons On Board] (integer) represents the number of people expected to be on board on arrival. Optional (provide -1 for unknown).
  • [Hazardous On Board] (bool - as string or integer) represents whether the vessel is expected to have hazardous on board. Optional (defaults to false).
  • [Billing Agent] (string) represents the company responsible for the payment of dues and charges. Required.
  • [Cancel] (bool - as string or integer) represents whether the forecast should be cancelled. Optional (defaults to false).
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with an ApiResult Description of "Forecast cannot be null", "UniqueIdentifier cannot be empty.", "UniqueIdentifier can not contain any of the following characters: \ / : ? " < > |", "ArrivalPort cannot be empty.", "The unique identifier has already been used by someone else.", "ETA cannot be null.", "ETA must be set.", "VesselName cannot be empty." or "Unable to add forecast to the queue." if there's a problem with the input.
GetWarnings

Returns a Warnings object representing all the warnings in force. This feed is not generally available to API users.

SOAP Usage: GetWarnings([API Key])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if the data is not ready

REST Usage: api/getwarnings.aspx?key=[API Key]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 204 if the data is not ready
GetQueuedForecast

Returns a Forecast object representing the current representation of the forecast in the queue and a log of events associated with the transactions.

SOAP Usage: GetQueuedForecast([API Key], [Unique Identifier])

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • [Unique Identifier] (string) represents a unique reference of the forecast being requested. Required.
  • Throws an exception if the [API Key] is invalid
  • Responds with null if a forecast with the specified [Unique Identifier] could not be found

REST Usage: api/getqueuedforecast.aspx?key=[API Key]&uniqueidentifier=[Unique Identifier]

  • [API Key] (string) represents a valid API Key (GUID) with permission to the method. Required.
  • [Unique Identifier] (string) represents a unique reference of the forecast being requested. Required.
  • Responds with HTTP Status Code 401 if the [API Key] is invalid
  • Responds with HTTP Status Code 404 if a forecast with the specified [Unique Identifier] could not be found

Output Examples