1. Introduction

This document describes a public REST API defined by the Niord Nautical Information Directory project as of January 2017.

The API detailed on this site does not cover the extensive REST API used internally by the Niord web application, but rather, describes the simple public REST interface that may be used by third-party applications (websites, apps, etc.) for fetching in-force navigational warnings (NW) and notices to mariners (NM).

An example client website using the Niord Public API can be found at nautiskinformation.soefartsstyrelsen.dk

The actual source for the API is available at the Niord Web Github Repository

2. Niord Public API

The Niord Public API is a simple public REST API for fetching nautical information, i.e. Navigational Warnings (NW) and Notices to Mariners (NM), from a Niord System.

The API requires no authentication or authorization, as it will only ever return public messages, that is, messages that are currently - or has been - published (in-force).

2.1. Niord Systems

Currently, there are three live Niord systems that may be used for accessing the public REST API.

System Base URL Description

DMA Alpha Site

niord.t-dma.dk

Used for alpha testing the Niord system. Contains junk data as well as production data from the Danish Maritime Authority.

DMA Prod Site

niord.dma.dk

Used in production by the the Danish Maritime Authority.

2.1.1. Swagger Integration

The Niord Public REST API is integrated with Swagger, which provides a web-based UI for inspecting and testing the REST API on a live system.

The Swagger API is available at /api.html.

Example: DMA Alpha Site Swagger Page.

2.2. Niord Message Model

The Niord Message Model, returned by the public REST API, is the combined model used to represent Navigational Warnings and Notices to Mariners.

The data model is detailed in the Niord Message Model document.

2.3. REST API

There are two main REST endpoints for fetching Niord messages:

Endpoint Description

/rest/public/v1/message/{messageId}

Used for fetching individual public (published, cancelled or expired) Niord messages by their ID.

/rest/public/v1/messages

Used for searching lists of public (published, cancelled or expired) Niord messages by various parameters.

The REST endpoints are detailed in the remainder of this section.

2.3.1. /rest/public/v1/message/{messageId}

This REST endpoint is used for fetching individual public (published, cancelled or expired) Niord messages by their ID. Parameters:

Parameter Type Example Description

messageId

String

NM-03-17

The message UID or short ID.

lang

String

en

Two-letter ISO 639-1 language code.
If defined, the returned message data will be filtered to only include the give language variant.
If un-specified, all language variants are returned.

externalize

boolean

true

Whether to rewrite all embedded links and paths to be absolute URL’s.
Default value is true.

dateFormat

String

UNIX_EPOCH

The date format to use for JSON date-time encoding. Either UNIX_EPOCH (default) or ISO_8601.

2.3.2. /rest/public/v1/messages

This REST endpoint is used for searching lists of public (published, cancelled or expired) Niord messages by various parameters:

Parameter Type Example Description

lang

String

en

Two-letter ISO 639-1 language code.
If defined, the returned message data will be filtered to only include the give language variant.
If un-specified, all language variants are returned.

domain

String[]

niord-nm

List of domain ID’s.
Each Niord system organizes messages into domains, e.g. for Navigational Warnings, Notices to Mariners, Firing Exercises, Almanacs, etc.

messageSeries

String[]

dma-nm

List of message series ID’s.
Each message is associated with a message series, as defined by the producing Niord system.
As an example, there may be separate messages series for local navigational warnings and other navigational warnings.

publication

String[]

642fda24-1b38-46b8-9003-8b79be079b1c

Some messages may have been published in publications, such as a weekly NtM. The publication parameter can be used to filter by specific publications.

areaId

String[]

urn:mrn:iho:country:dk

Messages may be associated with one or more area, as defined by the producing Niord System.
The areaId parameter can be used to filter messages by areas using either the internal ID or the MRN of the areas.

mainType

String[]

NM

Used to filter messages by their main type, i.e. "NM" or "NW".

wkt

String

POLYGON((7 54, 7 57, 13 56, 13 57, 7 54))

Used to filter messages by their geographical extent.
The geometry must be specified in the Well-known text format.

externalize

boolean

true

Whether to rewrite all embedded links and paths to be absolute URL’s.
Default value is true.

dateFormat

String

UNIX_EPOCH

The date format to use for JSON date-time encoding. Either UNIX_EPOCH (default) or ISO_8601.

2.4. Examples

The DMA Niord production system currently use the following domains (among others):

Domain ID Description

niord-nw

All Danish navigational warnings are produced in the "niord-nw" domain.

niord-nm

All Danish Notices to Mariners are produced in the "niord-nm" domain.

niord-fa

All Danish firing areas are defined as miscellaneous Notices to Mariners in the "niord-fa" domain.

niord-fe

The actual firing exercises are maintained as local navigational warnings in the "niord-fe" domain.

Fetch all in-force Danish NM’s - only return English translation:

curl -X GET --header 'Accept: application/json' \
   'https://niord.dma.dk/rest/public/v1/messages?lang=en&domain=niord-nm'

Fetch all in-force Danish NW’s, including firing exercises. Return all translations of the messages:

curl -X GET --header 'Accept: application/json' \
   'https://niord.dma.dk/rest/public/v1/messages?domain=niord-nw&domain=niord-fe'