Getting started with the Latest Vessel Information (LVI) Geospatial Web Service

Spire Maritime’s Geospatial Web Services™ (GWS) provide Open Geospatial Consortium (OGC) Web Map Services (WMS) and Web Feature Services (WFS) which allow on-demand access to Spire AIS data (Data-as-a-Service, DaaS) to retrieve vessel position, static, voyage, and historical track and position information.

• The WMS services generated from Spire AIS data allow users to get requested images of Spire AIS data in a variety of formats including PNG, JPEG, KML, etc.
• The WFS services generated from Spire AIS allow users to get features (data) in a variety of standard formats including CSV, GML, GeoJSON, and Shapefile.

An Identifier (eEID) has been generated for each unique vessel based on reported characteristics to help improve the detection of erroneous messages and track a vessel’s entire Voyage of Life (VoL).

Accessing Web Services

GWS uses HTTPS and user authentication via user token or user name and password to access information and is available at https://services.exactearth.com/gws.

LVI data set content

Data sets returned by GWS in response to requests made by end users contain fields in a specific sequential order. The order in which those fields are returned is documented in the Data Schema tables listed in this section. Data ingest methods that depend on field order, specifically commas separated values (.csv) format, need to take this into account. The data content description, including field descriptions and schemas are presented below.

Abstract

Latest Vessel Information by unique identifier (MMSI) in the last 7 days. LVI provides vessel information based on the latest position, static, and voyage information associated to any given MMSI or exactEarth ID (eEID).

Data Sources

Satellite-AIS (S-AIS) or Satellites and Terrestrial-AIS (S/T-AIS)

Geographic Area of Interest

Global or User-Defined

AOI Vessel Types

Class A and B

Geographic Data

Point (WGS84)

Vessel Identification Data Fields

mmsi, imo, vessel_name, callsign, vessel_type, vessel_type_code, vessel_type_cargo, flag_country, flag_code, vessel_class, vessel_type_main, vessel_type_sub, eeid

Vessel Positional Data Fields

ts_pos_utc, dt_pos_utc, position (Point – WGS84), longitude, latitude, sog, cog, rot, heading, nav_status, nav_status_code, source, ts_insert_utc, dt_insert_utc, message_type

Vessel Static/Voyage Information Data Fields

ts_static_utc, dt_static_utc, length, width, destination, eta, draught

Geometry

Point (WGS84)

LVI data set schema

[0] id      #Json
    fid.    #CSV, GML 2
    gml:id  #GML 3 & 3.2 Xml Attribute
[1] mmsi
[2] imo
[3] vessel_name
[4] callsign
[5] vessel_type
[6] vessel_type_code
[7] vessel_type_cargo
[8] vessel_class
[9] length
[10] width
[11] flag_country
[12] flag_code
[13] destination
[14] eta
[15] draught
[16] position
[17] longitude
[18] latitude
[19] sog
[20] cog
[21] rot
[22] heading
[23] nav_status
[24] nav_status_code
[25] source
[26] ts_pos_utc
[27] ts_static_utc
[28] ts_insert_utc
[29] dt_pos_utc
[30] dt_static_utc
[31] dt_insert_utc
[32] vessel_type_main
[33] vessel_type_sub
[34] message_type
[35] eeid

OGC Support

GWS supports all OGC WMS operations from implementation WMS 1.1.1 and WMS 1.3.0 and all OGC WFS operations from implementations WFS 1.0.0 and WFS 1.1.0, excluding Transaction.

User Authentication Support

GWS allows users to authenticate access to the services using either a token or basic authentication. Spire provides both a unique token and user name and password for each user. The [authKey] query string parameter of a WMS/WFS request provides the interface to enter a token to access the services using the following notation, “authKey=[TOKEN]”.

For basic authentication, users are required to enter user name and password credentials to access the services, for example, a web browser, OGC-compliant client, or application-level requestor. 

Web Map Service (WMS) example

GWS allows users to request images of geospatial data in a variety of formats. Here is an example of a WMS request for the latest vessel information data set as an image (PNG).

https://services.exactearth.com/gws/wms?service=WMS&version=1.3.0&request=GetMap&layers=exactAIS:LVI&styles=&bbox=-180.0,-90.0,180.0,90.0&width=640&height=480&crs=CRS:84&format=image/png

Web Feature Service (WFS) examples

GWS allows users to request data sets of geospatial data. Here is an example of a sample WFS GML request for the latest vessel information data set:

<gml:featureMembers>
 <exactAIS:LVI gml:id="48752423661E2262128">
  <exactAIS:mmsi>372934000</exactAIS:mmsi>
  <exactAIS:imo>9335173</exactAIS:imo>
  <exactAIS:vessel_name>COSCO BOSTON</exactAIS:vessel_name>
  <exactAIS:callsign>3ELF2</exactAIS:callsign>
  <exactAIS:vessel_type>Cargo</exactAIS:vessel_type>
  <exactAIS:vessel_type_code>70</exactAIS:vessel_type_code>
  <exactAIS:vessel_type_cargo/>
  <exactAIS:vessel_class>A</exactAIS:vessel_class>
  <exactAIS:length>293</exactAIS:length>
  <exactAIS:width>32</exactAIS:width>
  <exactAIS:flag_country>Panama</exactAIS:flag_country>
  <exactAIS:flag_code>372</exactAIS:flag_code>
  <exactAIS:destination>SHK</exactAIS:destination>
  <exactAIS:eta>05102000</exactAIS:eta>
  <exactAIS:draught>10.4</exactAIS:draught>
  <exactAIS:position>
   <gml:Point srsName="urn:x-ogc:def:crs:EPSG:4326" srsDimension="2">
    <gml:pos>24.54373333 119.41136667</gml:pos>
   </gml:Point>
  </exactAIS:position>
  <exactAIS:longitude>119.41136666666667</exactAIS:longitude>
  <exactAIS:latitude>24.543733333333332</exactAIS:latitude>
  <exactAIS:sog>19.0</exactAIS:sog>
  <exactAIS:cog>226.0</exactAIS:cog>
  <exactAIS:rot>0.0</exactAIS:rot>
  <exactAIS:heading>226.0</exactAIS:heading>
  <exactAIS:nav_status>Under Way Using Engine</exactAIS:nav_status>
  <exactAIS:nav_status_code>0</exactAIS:nav_status_code>
  <exactAIS:source>T-AIS</exactAIS:source>
  <exactAIS:ts_pos_utc>20190509225603</exactAIS:ts_pos_utc>
  <exactAIS:ts_static_utc>20190509225005</exactAIS:ts_static_utc>
  <exactAIS:ts_insert_utc>20190509225608</exactAIS:ts_insert_utc>
  <exactAIS:dt_pos_utc>2019-05-09 22:56:03</exactAIS:dt_pos_utc>
  <exactAIS:dt_static_utc>2019-05-09 22:50:05</exactAIS:dt_static_utc>
  <exactAIS:dt_insert_utc>2019-05-09 22:56:08</exactAIS:dt_insert_utc>
  <exactAIS:vessel_type_main>Container Ship</exactAIS:vessel_type_main>
  <exactAIS:vessel_type_sub/>
  <exactAIS:message_type>1</exactAIS:message_type>
  <exactAIS:eeid>4875242366182262128</exactAIS:eeid>
 </exactAIS:LVI>
</gml:featureMembers>

Data schema example

GWS allows users to request the schema of the geospatial data services. A sample WFS request, DescribeFeatureType, for the latest vessel information data set is included below.

https://services.exactearth.com/gws/wfs?request=DescribeFeatureType&service=wfs&version=1.1.0&typeName=exactAIS:LVI

<xsd:extension base="gml:AbstractFeatureType">
 <xsd:sequence>
  <xsd:element maxOccurs="1" minOccurs="0" name="mmsi" nillable="true" type="xsd:long"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="imo" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_name" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="callsign" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_type" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_type_code" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_type_cargo" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_class" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="length" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="width" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="flag_country" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="flag_code" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="destination" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="eta" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="draught" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="position" nillable="true" type="gml:PointPropertyType"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="longitude" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="latitude" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="sog" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="cog" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="rot" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="heading" nillable="true" type="xsd:double"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="nav_status" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="nav_status_code" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="source" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="ts_pos_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="ts_static_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="ts_insert_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="dt_pos_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="dt_static_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="dt_insert_utc" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_type_main" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="vessel_type_sub" nillable="true" type="xsd:string"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="message_type" nillable="true" type="xsd:int"/>
  <xsd:element maxOccurs="1" minOccurs="0" name="eeid" nillable="true" type="xsd:long"/>
 </xsd:sequence>
</xsd:extension>

Find MMSIs example

Here is an example of a sample WFS request, GetFeature, to find the Maritime Mobile Service Identity (MMSI) number of a vessel by International Maritime Organization (IMO) number from the Latest Vessel Information (LVI) service.

https://services.exactearth.com/gws/wfs?request=GetFeature&service=wfs&version=1.1.0&typeName=exactAIS:LVI&maxFeatures=1&outputFormat=gml3&propertyName=mmsi,vessel_name,imo,eeid&filter=<Filter><PropertyIsEqualTo><PropertyName>imo</PropertyName><Literal>9335173</Literal></PropertyIsEqualTo></Filter>

<wfs:FeatureCollection>
 <gml:featureMembers>
  <exactAIS:LVI gml:id="48752423661E2262128">
   <exactAIS:mmsi>372934000</exactAIS:mmsi>
   <exactAIS:imo>9335173</exactAIS:imo>
   <exactAIS:vessel_name>COSCO BOSTON</exactAIS:vessel_name>
   <exactAIS:eeid>48752423661E2262128</exactAIS:eeid>
  </exactAIS:LVI>
 </gml:featureMembers>
</wfs:FeatureCollection>

Find eEID Example

GWS 2.0 introduced the concept of an exactEarth Identifier (eEID) that is given to vessels based on their underlying characteristics. An eEID is used to uniquely target a vessel when working with Spire services.

Here is an example of a sample WFS request, GetFeature, to find the eEID of a vessel with an existing Maritime Mobile Service Identity (MMSI) number from the Latest Vessel Information (LVI) service.

https://services.exactearth.com/gws/wfs?request=GetFeature&service=wfs&version=1.1.0&typeName=exactAIS:LVI&maxFeatures=1&outputFormat=gml3&propertyName=mmsi,eeid&filter=<Filter><PropertyIsEqualTo><PropertyName>mmsi</PropertyName><Literal>372934000</Literal></PropertyIsEqualTo></Filter>

<wfs:FeatureCollection>
 <gml:featureMembers>
  <exactAIS:LVI gml:id="48752423661E2262128">
   <exactAIS:mmsi>372934000</exactAIS:mmsi>
   <exactAIS:eeid>48752423661E2262128</exactAIS:eeid>
  </exactAIS:LVI>
 </gml:featureMembers>
</wfs:FeatureCollection>

Web Services filtering

OGC Filtering

GWS supports OGC Filtering to allow for dynamic/ad-hoc customization of data responses based on geography, time, and AIS message attributes. The below table provides a set of examples using OGC XML-based Filtering.

Web Services filtering examples

Here are two LVI WMS 1.30 examples:

• Provide a PNG image for a specific MMSI from the latest vessel information data set.https://services.exactearth.com/gws/wms?service=WMS&version=1.3.0&request=GetMap&layers=exactAIS:LVI&styles=&bbox=-180.0,-90.0,180.0,90.0&width=640&height=480&crs=crs:84&format=image/png&filter=<Filter><PropertyIsEqualTo><PropertyName>mmsi</PropertyName><Literal>372934000</Literal></PropertyIsEqualTo></Filter>
• Provides a PNG image for all vessels with Speed over Ground (SOG) reported between 10 and 20 knots within a specific area of interest using the BBOX parameter from the latest vessel information data set.https://services.exactearth.com/gws/wms?service=WMS&version=1.3.0&request=GetMap&layers=exactAIS:LVI&styles=&bbox=-83,-23,32,34&width=660&height=330&crs=crs:84&format=image/png&filter=<Filter><PropertyIsBetween><PropertyName>sog</PropertyName><LowerBoundary><Literal>10</Literal></LowerBoundary><UpperBoundary><Literal>20</Literal></UpperBoundary></PropertyIsBetween></Filter>

Here is a LVI WFS 1.1.0 example:

• Provides a JSON output for 10 vessels within a specific area of interest from the latest vessel information data set.https://services.exactearth.com/gws/wms?service=WFS&version=1.1.0&request=GetFeature&typeName=exactAIS:LVI&outputFormat=json&maxFeatures=10&filter=<Filter xmlns:gml=”http://www.opengis.net/gml”><Intersects><PropertyName>position</PropertyName><gml:Polygon xmlns:gml=”http://www.opengis.net/gml” srsName=”EPSG:4326″><gml:exterior><gml:LinearRing><gml:posList>-55 -8 -55 8 55 8 55 -8 -55 -8</gml:posList></gml:LinearRing></gml:exterior></gml:Polygon></Intersects></Filter>

CQL Filtering

Extended Common Query Language (ECQL) is a query language supported by GWS and offers familiar text-based syntax with strong similarities to SQL for filtering. For more information, please refer to https://docs.geoserver.org/stable/en/user/filter/ecql_reference.html#filter-ecql-reference.

The below table provides a set of examples using ECQL:

Further customization

Layer style and Symbolization support

GWS allows users to request styles (symbolization) to be applied to Web Map Service (WMS) GetMap (image) responses. exactEarth provides a variety of styles that can be used to customize the look and feel of rendered maps. The [styles] query string parameter of a WMS request provides the interface to enter a style to define the symbology to apply to the map output, “styles=[STYLE]”.

Vessel (Default)

Vessel symbol, single color, rotation by [cog]

VesselByType

Vessel symbol, color by [vessel_type], rotation by [cog]

VesselBySpeed

Vessel symbol, single color, rotation by [cog], leader line symbol by [sog]

VesselBySpeedGrouped

Vessel symbol, color by [sog], rotation by [cog]

VesselByTypeSpeed

Vessel symbol, color by [vessel_type_code], rotation by [cog], leader line symbol by [sog]

VesselSpeedVector

Leader line symbol by [sog], rotation by [cog]

VesselBySource

Vessel symbol, color by [source], rotation by [cog]

VesselByClass

Vessel symbol, color by [class], rotation by [cog]

VesselLabel

Vessel symbol, single color, rotation by [cog], label by [vessel_name]

VesselLabelOverlay

Label by [vessel_name]

VesselLabelDateTime

Circle point symbol, single color, label by [ts_pos_utc]

VesselLabelDateTimeOverlay

Label by [ts_pos_utc]

Legend support

GWS allows users to generate legends based on supported styles (symbolization). The [request] query string parameter, GetLegendGraphic, of a WMS request provides the interface to generate legends. The [scale], [style], and [layer] query string parameters control the appearance of the legend. The below WMS 1.3.0 request provides a PNG image (legend) for the latest vessel information data set using the [style] and [scale] parameters to generate a legend based on the VesselByTypeSpeed style at a map scale of 1:80,000.

https://services.exactearth.com/gws/wms?request=GetLegendGraphic&service=WMS&format=image/png&version=1.3.0&style=VesselByTypeSpeed&layer=exactAIS:LVI&scale=80000&legend_options=fontStyle:bold;forceLabels:on;fontName:Helvetica;fontAntiAliasing:true;fontColor:0x000000;fontSize:9;bgColor:0xFFFFFF;dpi:120;

Web Services WMS Custom Symbolization

GWS supports custom symbology to allow for dynamic/ad-hoc rendering of vessels. The [env] query string parameter of a WMS request provides the interface to change the vessel symbols using the following notation, “env=[PARAM]:[VALUE]”. [env] query string parameters are delimited by “;”, for example, “env=[PARAM1]:[VALUE1];[PARAM2]:[VALUE2]”.

Custom color

To adjust the rendering of vessels by color, add the [color] parameters to the [env] query string parameter of a WMS request using the following notation, “env=color:hexadecimal”. The hexadecimal is an RGB color code, defined as RRGGBB. The below WMS 1.3.0 request provides a PNG image for all global vessels from the latest vessel information data set using the [env] parameter specifying all vessel be rendered as magenta (FF3366).

https://services.exactearth.com/gws/wms?service=WMS&version=1.3.0&request=GetMap&layers=exactAIS:LVI&styles=&bbox=-180.0,-90.0,180.0,90.0&width=640&height=480&crs=crs:84&format=image/png&env=color:FF3366

Optional parameters

GWS supports optional parameters and capabilities to enhance the usability of the service.

Maximum Features (maxFeatures)

Provides an ability to limit the number of features by request to the WFS services.

https://services.exactearth.com/gws/wfs?service=wfs&version=1.1.0&request=GetFeature&typeNames=exactAIS:LVI&outputFormat=json&maxFeatures=10

Sorting (sortBy)

Provides an ability to sort the values in a column in ascending or descending order by request to the WFS services. Sorting by ascending order is the default setting, using “+D” will change the response to sorting by descending order.

https://services.exactearth.com/gws/wfs?service=wfs&version=1.1.0&request=GetFeature&typeNames=exactAIS:LVI&maxFeatures=1&outputFormat=json&sortBy=ts_pos_utc+D

Feature Counts (resultType)

Provides an ability to retrieve the number of features by request to the WFS services.

https://services.exactearth.com/gws/wfs?service=wfs&version=1.1.0&request=GetFeature&typeName=exactAIS:LVI&resulttype=hits

Fields / Columns (propertyName)

Provides an ability to specify the output fields / columns per request. The [propertyName] query string parameter of a WFS request provides the interface to limit the fields / columns returned in the GetFeature request, for example, “propertyName=eeid,mmsi,vessel_name,ts_pos_utc”.

https://services.exactearth.com/gws/wfs?typenames=exactAIS:LVI&service=wfs&version=1.1.0&request=getfeature&propertyName=eeid,mmsi,vessel_name,ts_pos_utc&outputFormat=json&maxFeatures=1

Data definition guide

MMSI

Maritime Mobile Service Identity (MMSI) [Number]

IMO

International Maritime Organization (IMO) [Number]

VESSEL_NAME

Vessel Name [Text]

CALLSIGN

Vessel Call Sign [Text]

VESSEL_TYPE

Vessel Type [Text]

VESSEL_TYPE_CODE

Vessel Type Code [Number]

VESSEL_TYPE_CARGO

Vessel Type Cargo [Text]

VESSEL_TYPE_MAIN

Vessel Type Main [Text]

VESSEL_TYPE_SUB

Vessel Type Sub-Category [Text]

FLAG_COUNTRY

Country of Registration [Text]

FLAG_CODE

Country of Registration Code [Number]

VESSEL_CLASS

Class of Vessel (A/B) [Text]

EEID

exactEarth Identifier (eEID) [Number]

TS_POS_UTC

Date and Time of Last Position AIS Message in UTC [YYYYMMDDHHmmSS]

DT_POS_UTC

Date and Time of Last Position AIS Message in UTC [YYYY-MM-DD HH24:MI:SS]

POSITION

WGS84 Point, Geographic Location [Geometry]

SEGMENT

WGS84 LineString/MultiLineString, Geographic Segment [Geometry]

LONGITUDE

WGS 84 Longitude Coordinate [Number, Decimal Degrees]

LATITUDE

WGS 84 Latitude Coordinate [Number, Decimal Degrees]

SOG

Speed over Ground [Number, Knots]

COG

Course over Ground [Number, Degrees]

ROT

Rate of Turn [Number, Degrees / Min]

HEADING

Heading [Number, Degrees]

NAV_STATUS

Navigational Status [Text]

NAV_STATUS_CODE

Navigational Status Code [Number]

SOURCE

Source of Position Report (Satellite AIS [S-AIS], Terrestrial AIS [T-AIS], or Vessel AIS [V-AIS]) [Text]

FROM_LONGITUDE

WGS 84 Longitude Coordinate [Number, Decimal Degrees]

FROM_LATITUDE

WGS 84 Latitude Coordinate [Number, Decimal Degrees]

DTG

ISO 8601 Date and Time of Last Position AIS Message in UTC [YYYY-MM-DDTHH:mm:ssZ]

TS_STATIC_UTC

Date and Time of Last Static AIS Message in UTC [YYYYMMDDHHmmSS]

DT_STATIC_UTC

Date and Time of Last Static AIS Message in UTC [YYYY-MM-DD HH24:MI:SS]

LENGTH

Length of Bow to Main Tower and Main Tower to Stern [Number, Metres]

WIDTH

Length of Port to Main Tower and Main Tower to Starboard [Number, Metres]

DESTINATION

Port of Destination [Text]

ETA

Month, Day, Hour, and Minute of Estimated Time of Arrival in UTC [MMDDHHmm]

DRAUGHT

Vessel Draught [Number, Metres]

TS_INSERT_UTC

Date and Time of Last Insert in UTC [YYYYMMDDHHmmSS]

DT_INSERT_UTC

Date and Time of Last Insert in UTC [YYYY-MM-DD HH24:MI:SS]

MESSAGE_TYPE

AIS Position Message type (1,2,3,4,18,19,27) [Number]