1. Help Center
  2. Spire Sense Maritime
  3. Spire Maritime 2.0 - GraphQL API

Maritime 2.0 GraphQL - Vessels Timestamp Filters

Explaining the LastTimestamp filter in Maritime 2.0 GraphQL Vessels

From 2022-06 Maritime 2.0 graphQL for vessels will gain a new filter, lastTimestamp.

Unlike the filter lastPositionUpdate which filters for vessels by the time when a position update was received, the new filter lastTimestamp filters vessels on the message timestamp of any update from AIS static or position messages. 

If lastTimestamp filter is not specified in a query then it will be set by default to filter out vessels with no AIS message in the last 30 days. 

This is intended to not return, unless specifically required, vessels that have not been updated in the previous 30 days. This is intended to reduce the volume of data being returned, unless vessels with older updates are specifically requested. 

Example, comparing the use of lastTimestamp and lastPositionUpdate filter. 

query {
  vessels( lastPositionUpdate:{startTime:"2022-05-23T00:00:00.00Z"}
  ) {
  pageInfo { hasNextPage endCursor } } }

returns

{   "data": {
  "vessels": { "totalCount": { "relation": "LOWER_OR_EQUAL", "value": 210392 }

In the example above, requesting vessels with position updates returns an estimates 210,392 vessels

However, using the lastTimestamp filter as below, can return a slightly higher number of vessels, as it now includes vessels that have only had updates from AIS static messages too.

{  "data": {
  "vessels": { "totalCount": { "relation": "LOWER_OR_EQUAL", "value": 211921 } } }

The higher number of vessels returned using the lastTimestamp filter, 211921 compared to 210392, indicates that about 1500 vessels had updates from Static AIS messages but not yet from AIS position messages in the period being queried. This can be to many reasons including latency in AIS messages or updates to the system. 

The new filter lastTimestamp allows vessels with to be queried by when AIS messages were last received. Note this is different than when the updates occurred as is used in the lastPositionTimestamp. 

 

Example of filter differences

An AIS position message transmitted at 2022-05-23T09:59 and updated into the system at 2022-05-23T10:02 (latency of 2 minutes)

Would be returned by a query using filter 

lastPositionUpdate:{startTime:"2022-05-23T10:00:00.00Z"}

but not by a query using filter 

lastPositionUpdate:{startTime:"2022-05-23T09:00:00.00Z" endTime:"2022-05-23T09:59:59.59Z"}

This is because the updateTimestamp would be 10:01 and outside the filtered time range

However, after being updated into the API database, the vessel with the same position message would be returned by a filter 

lastTimestamp:{startTime:"2022-05-23T09:00:00.00Z" endTime:"2022-05-23T09:59:59.59Z"}

If the query is run after 10:01 when the message is recorded in the database

 

Querying without timestamp filters

Now, compare querying graphQL vessels without a timestamp.

Using this query to return all vessels by shipType values that we consider the Merchant Fleet

query {
  vessels( 
   shipType: [CAR_CARRIER,COMBINATION_CARRIER,CONTAINER,DRY_BULK,GENERAL_CARGO
    ,LIVESTOCK,REEFER,ROLL_ON_ROLL_OFF,VEHICLE_PASSENGER,GAS_CARRIER
    ,GENERAL_TANKER,LNG_CARRIER,TANKER_CHEMICALS,TANKER_CRUDE,TANKER_PRODUCT]
  ) {
  totalCount{ relation value } } }

on the graphQL Vessels system pre release of the default lastTimestamp filter we get the following result

{  "data": {
  "vessels": { "totalCount": { "relation": "LOWER_OR_EQUAL", "value": 172075 }

On the updated graphQL Vessels system with the default lastTimestamp filter set to 30 days we get the following result

{  "data": {
  "vessels": { "totalCount": { "relation": "LOWER_OR_EQUAL", "value": 165933 }

Showing that about 6000 vessels have been excluded from query results because they do not have recent messages of any kind.

You can of course choose to still receive reports of vessels with updates more than 30 days old by using the lastTimestamp filter to specifically set a time from which all updated vessels are received filtered by any other parameters specified.

IE. 

query {
  vessels( lastTimestamp:{startTime:"2022-01-01T00:00:00.00Z"}
    shipType: [CAR_CARRIER,COMBINATION_CARRIER,CONTAINER,DRY_BULK,GENERAL_CARGO
    ,LIVESTOCK,REEFER,ROLL_ON_ROLL_OFF,VEHICLE_PASSENGER,GAS_CARRIER
    ,GENERAL_TANKER,LNG_CARRIER,TANKER_CHEMICALS,TANKER_CRUDE,TANKER_PRODUCT]
  ) {
  totalCount{ relation value } } }

which returns

{  "data": {
  "vessels": {"totalCount": { "relation": "LOWER_OR_EQUAL", "value": 165938 }