Map an AIS Vessel Report

Automatic Identification System (AIS) broadcasts vessel identity, position, and movement over radio. This example maps an AIS position report to a vessel Object in [R]DP. Its Maritime Mobile Service Identity (MMSI), a nine-digit radio identifier, connects successive positions to the same vessel.

Source data

The input represents an AIS Class A position message (message type 1) as JSON. Coordinates use WGS-84, the geographic reference used by GPS. Speed arrives in knots; angles are clockwise from true north.

The input includes a complete UTC timestamp in observedAt; the AIS message supplies only seconds within a minute. reportId identifies this observation and receivedAt records when it was copied. The US Coast Guard reference describes the underlying AIS fields.

{
  "messageType": 1,
  "mmsi": "367123456",
  "latitudeDegrees": 36.85,
  "longitudeDegrees": -75.98,
  "speedOverGroundKnots": 12.0,
  "courseOverGroundDegrees": 90.0,
  "trueHeadingDegrees": 88.0,
  "navigationStatus": 0,
  "observedAt": "2026-10-01T12:00:00Z",
  "receivedAt": "2026-10-01T12:00:02Z",
  "reportId": "ais-report-001"
}

Field mapping

The vessel’s identity connects its position updates, while WDM’s position and motion fields let clients plot and follow it. WDM stores speed in meters per second so clients can compare it across feeds.

Course over ground is the direction the vessel travels; heading is the direction its bow points. They can differ, for example when currents move the vessel sideways, so WDM keeps them separate.

Source WDM field Explanation

mmsi

id, identities, typeInfo.maritime.mmsi

mmsi:367123456 connects updates to one vessel. identities retains the source identifier, and the maritime field makes it available to vessel-specific queries. A string preserves leading zeros.

Latitude and longitude

location.position

Decimal degrees copy directly into the map position; the source supplies no altitude.

speedOverGroundKnots

motion.speedMps

Ground speed helps clients follow the vessel’s movement alongside its position and course.

courseOverGroundDegrees, trueHeadingDegrees

motion.courseOverGroundDegrees, location.orientation.headingDegrees

90 degrees describes travel eastward; 88 degrees describes the bow’s orientation. Keeping both lets clients distinguish movement from orientation.

navigationStatus: 0

typeInfo.maritime.navStatus

AIS’s "under way using engine" state maps to NAVIGATION_STATUS_UNDERWAY.

Observation and capture times

provenance.updatedAt, externalRefs[].capturedAt, ttl

Observation and capture times remain separate. This example’s expiry timestamp, ttl, is observation time plus 60 seconds, limiting how long clients treat the position as current.

Source JSON

externalRefs[].payload

A Struct, a protobuf container for JSON-like fields, retains the complete input. Original radio-message bytes are unavailable.

ONTOLOGY_CATEGORY_PLATFORM classifies the vessel as a vehicle. Its display name is MMSI 367123456 because this message supplies no vessel name. AIS static and voyage messages can add names, callsigns, vessel identifiers, and destinations to the same Object. Affiliation stays unset because this input does not establish it.

This position message supplies no military symbol code or vessel type, so the example leaves symbology unset.

Unknown values and reporting limits

AIS reserves some numbers to mean "unknown" or "beyond the reporting range." Treating these as measurements would create false positions or speeds:

  • Latitude 91 degrees or longitude 181 degrees means unavailable; position needs both valid coordinates.

  • Speed over ground (SOG) code 1023 means unavailable; 1022 means at least 102.2 knots. The latter is a lower bound, which the retained source preserves.

  • Course over ground (COG) code 3600 and true heading 511 mean unavailable.

Zero speed is a valid measurement.

WDM Object

The record uses ProtoJSON, protobuf’s JSON representation:

{
  "id": "mmsi:367123456",
  "security": {
    "raw": "UNCLASSIFIED",
    "components": {
      "classification": "UNCLASSIFIED",
      "ownerProducer": [
        "USA"
      ]
    }
  },
  "identities": [
    {
      "system": "mmsi",
      "identifier": "367123456"
    }
  ],
  "flags": {
    "isSimulated": true
  },
  "status": "OBJECT_STATUS_ACTIVE",
  "ttl": "2026-10-01T12:01:00Z",
  "provenance": {
    "id": "ais-report-001",
    "name": "AIS demo source",
    "updatedAt": "2026-10-01T12:00:00Z",
    "producer": "example-ais-adapter-v1"
  },
  "name": "MMSI 367123456",
  "ontology": {
    "category": "ONTOLOGY_CATEGORY_PLATFORM"
  },
  "typeInfo": {
    "maritime": {
      "mmsi": "367123456",
      "navStatus": "NAVIGATION_STATUS_UNDERWAY"
    }
  },
  "location": {
    "position": {
      "latitudeDegrees": 36.85,
      "longitudeDegrees": -75.98
    },
    "orientation": {
      "headingDegrees": 88.0
    }
  },
  "motion": {
    "speedMps": 6.173333333333333,
    "courseOverGroundDegrees": 90.0
  },
  "externalRefs": [
    {
      "typeUrl": "type.googleapis.com/google.protobuf.Struct",
      "externalId": "ais-report-001",
      "sourceSystem": "ais-demo-source",
      "payload": {
        "@type": "type.googleapis.com/google.protobuf.Struct",
        "value": {
          "@type": "com.example.mapping.v1.DecodedSourceRecord",
          "value": {
            "format": "AIS",
            "profile": "Class A message 1; normalized fixture contract",
            "mediaType": "application/json",
            "representation": "decoded_record",
            "originalWireDataAvailable": false,
            "record": {
              "messageType": 1,
              "mmsi": "367123456",
              "latitudeDegrees": 36.85,
              "longitudeDegrees": -75.98,
              "speedOverGroundKnots": 12.0,
              "courseOverGroundDegrees": 90.0,
              "trueHeadingDegrees": 88.0,
              "navigationStatus": 0,
              "observedAt": "2026-10-01T12:00:00Z",
              "receivedAt": "2026-10-01T12:00:02Z",
              "reportId": "ais-report-001"
            }
          }
        }
      },
      "capturedAt": "2026-10-01T12:00:02Z",
      "label": "Decoded AIS position report"
    }
  ]
}

See Publish Object for how to send the record and Preserve Source Data for payload packing.