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

Maritime 2.0 GraphQL. When Vessels Change MMSI Number

What happens in Maritime 2.0 graphQL API when a vessel changes it's IMO number.

Vessels transmit AIS messages using an MMSI number as the vessel identifier. 

85% of AIS messages are from one of two message types, position messages and static voyage messages.

In position messages, MMSI number is the only identifier. This links position messages to static voyage messages which contain more vessel identification information such as:

  • IMO number, the only consistent identifier of large vessels -never changes
  • Name, the name of the vessel -can change
  • Dimensions, distances from the AIS transmitter to both sides, stern, and bow of the vessel - though mainly static can be adjusted by reassessment or physical changes
  • Callsign, a radio communication identifier linked to the flag registration -t will change along with the MMSI number when a vessel changes flag 

When a vessel changes its flag (and, consequently, its MMSI number), it will transmit all AIS messages with its new MMSI number, never again including its old MMSI number. .

Below is an aggregation of AIS static data values received when a vessel changes MMSI number

The vessel with IMO 9150406 stopped transmitting AIS messages using the MMSI number 311000889. The last AIS message using that MMSI number was received at 22-04-11 08:56:00 UTC. From then on, the vessel starts transmitting AIS messages using the MMSI number 538009951, with the first AIS static message using that MMSI number being received at 2022-04-11 09:26:02 UTC. All subsequent AIS messages from this vessel use that MMSI number. 

In Maritime 2.0, when a vessel changes MMSI number like this, as in the previous Spire Vessels API product that Maritime 2.0 replaces, the old version of the vessel remains in the system and a new vessel is created that reports the new MMSI and IMO combination. 

This means that when querying based on IMO number or name (two identifiers the same in both old and new versions of the MMSI number) then both the old and new version of a vessel will be returned.

However when querying on time-based updates with the lastPositionUpdated filter, then only the new vessel would be returned. 

This is demonstrated in the sample GraphQL API query and results below:

GraphQL query for IMO of vessel that changed flag and MMSI

query chars {
 vessels( imo:9150406 ) 
 { totalCount { value  relation }
   nodes {  id
      staticData { imo mmsi  flag name callsign timestamp
       shipType dimensions { a b c d width length } }
      lastPositionUpdate {
       collectionType  course heading latitude longitude
       navigationalStatus  rot speed timestamp updateTimestamp
     }
     currentVoyage {destination draught eta timestamp }
     characteristics { basic { capacity { deadweight grossTonnage  }
         history { builtYear } vesselTypeAndTrading { vesselSubtype  }
       } } } } }

 

API results showing both old and new versions of the vessel.

Note the old version of the vessel reported using MMSI 311000889 and the new version of the vessel reported using the MMSI 538009951.

{  "data": { "vessels": { "pageInfo": { "hasNextPage": false, "endCursor": null },
     "totalCount": { "value": 1, "relation": "EQUAL" },
     "nodes": [
       { "id": "5c0f196a-bc12-42e5-8d6d-6f14983a8e3c",
         "staticData": { "imo": 9150406, "mmsi": 538009951,
           "name": "SMILEY LADY", "timestamp": "2022-04-11T11:32:22.000Z",
           "shipType": "CONTAINER", "callsign": "V7A5382",
           "dimensions": { "a": 165, "b": 18, "c": 12, "d": 13,
             "width": 25, "length": 183 } },
         "lastPositionUpdate": { "collectionType": "TERRESTRIAL",
           "course": 35.6, "heading": 236, "rot": 0, "speed": 0,
           "latitude": 25.430783333333334, "longitude": 55.07663166666667,
           "navigationalStatus": "RESTRICTED_MANEUVERABILITY",
           "timestamp": "2022-04-11T09:25:38.847Z",
           "updateTimestamp": "2022-04-11T09:25:42.855Z" },
         "currentVoyage": { "destination": "DUBAI ANCHORAGE C",
           "matchedPort": { "port": { "name": "Dubai", "unlocode": "AEDXB" } },
           "draught": 6.2, "eta": "2022-04-06T14:30:00.000Z",
           "timestamp": "2022-04-11T11:32:22.000Z",
           "updateTimestamp": "2022-04-11T11:32:24.742Z" },
         "characteristics": { "basic": { "capacity": {
               "deadweight": 23075, "grossTonnage": 16803 },
             "history": { "builtYear": 1999 },
             "vesselTypeAndTrading": { "vesselSubtype": null } }
         } } ] } },
 "extensions": { "requestId": "e02f9c9d-d711-4407-bd2f-f31bdbc722f3",
   "requestQuota": { "limit": "60 req/m (burst 60)", "remaining": 59 } } }

API results when filtering only on recent updates, as in those received since the vessel changed MMSI number. Only the new version of the vessel is returned.

{    "data": {
       "vessels": { "totalCount": { "value": 1, "relation": "EQUAL" },
           "nodes": [
              { "id": "e708c552-afd4-41ce-b5a3-f05efb83e7c9",
                   "staticData": {
                       "imo": 9150406, "mmsi": 538009951, "flag": "MH",
                       "name": "SMILEY LADY", "callsign": "V7A5382",
                       "timestamp": "2022-04-11T11:32:22.000Z",
                       "shipType": "CONTAINER",
                       "dimensions": { "a": 165, "b": 18, "c": 12, "d": 13,
                           "width": 25, "length": 183 } },
                   "lastPositionUpdate": {
                       "collectionType": "TERRESTRIAL",
                       "course": 86.3, "heading": 279,
                       "latitude": 25.42983333333333,
                       "longitude": 55.077088333333336,
                       "navigationalStatus": "AT_ANCHOR",
                       "rot": 0, "speed": 0.1,
                       "timestamp": "2022-04-11T15:38:59.000Z",
                       "updateTimestamp": "2022-04-11T15:39:05.280Z"
                   },
                   "currentVoyage": {
                       "destination": "DUBAI ANCHORAGE C", "draught": 6.2,
                       "eta": "2022-04-06T14:30:00.000Z",
                       "timestamp": "2022-04-11T11:32:22.000Z" },
                   "characteristics": {
                       "basic": { "capacity": {
                               "deadweight": 23075, "grossTonnage": 16803 },
                           "history": { "builtYear": 1999 },
                           "vesselTypeAndTrading": { "vesselSubtype": null } }
                   } } ] } },
   "extensions": { "requestId": "e9a0c3b3-72bf-45ec-b198-23b1a1491252",
       "requestQuota": { "limit": "60 req/m (burst 60)", "remaining": 59 } } }