> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AIS Maritime schema

> Full field reference for the AIS Maritime dataset — 1.4M vessel positions with identity enrichment, behavior anomaly flags, and port-event linkage.

The AIS Maritime dataset contains \~1.4M normalized vessel positions sourced from terrestrial and satellite AIS receivers, enriched with vessel identity from IMO registries, behavior anomaly detection, and linkage to Codex port events. Records are ingested continuously and published as monthly immutable snapshots.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields

### Vessel identity

| Field         | Type    | Nullable | Description                                                                                                                             |
| ------------- | ------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------- |
| `imo`         | integer |    yes   | IMO number (7-digit). Primary vessel identifier per IMO A.600(15).                                                                      |
| `mmsi`        | string  |    yes   | Maritime Mobile Service Identity (9-digit). Fallback identifier.                                                                        |
| `vessel_name` | string  |    yes   | Vessel name (max 20 ASCII characters per AIS message 5).                                                                                |
| `call_sign`   | string  |    yes   | Radio call sign (max 7 characters).                                                                                                     |
| `flag_state`  | string  |    yes   | ISO 3166-1 alpha-3 country code.                                                                                                        |
| `vessel_type` | string  |    yes   | Codex 6-category enum: `container`, `tanker_crude`, `tanker_product`, `bulker`, `fishing`, `other`. Raw ITU code preserved in metadata. |
| `dwt`         | numeric |    yes   | Deadweight tonnage in metric tonnes.                                                                                                    |
| `length_oa`   | numeric |    yes   | Length overall in meters.                                                                                                               |
| `beam`        | numeric |    yes   | Beam in meters.                                                                                                                         |
| `draught`     | numeric |    yes   | Draught in meters.                                                                                                                      |

### Position and kinematics

| Field        | Type        | Nullable | Description                                                                                 |
| ------------ | ----------- | :------: | ------------------------------------------------------------------------------------------- |
| `lat`        | float       |    no    | WGS84 latitude.                                                                             |
| `lng`        | float       |    no    | WGS84 longitude.                                                                            |
| `speed`      | float       |    yes   | Speed over ground in knots (0.1 kn resolution).                                             |
| `course`     | float       |    yes   | Course over ground in degrees (0.1° resolution).                                            |
| `heading`    | float       |    yes   | True heading in degrees (1° resolution).                                                    |
| `nav_status` | string      |    yes   | AIS navigation status (0–15). Codex emits both the numeric code and a human-readable label. |
| `rot`        | float       |    yes   | Rate of turn in degrees per minute (decoded from AIS-coded ±127 value).                     |
| `timestamp`  | timestamptz |    no    | UTC timestamp of the position fix.                                                          |
| `h3_index`   | string      |    no    | H3 resolution-8 cell derived from `lat`/`lng`.                                              |

### Codex enrichments

| Field                   | Type    | Nullable | Description                                                                                                                          |
| ----------------------- | ------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------ |
| `behavior_anomaly_flag` | boolean |    no    | `true` when kinematic or behavioral anomaly detected (AIS gap, speed anomaly, or route deviation).                                   |
| `port_event_id`         | UUID    |    yes   | Links to the corresponding event in [Events Timeline](/codex/schemas/events-timeline) when the position falls inside a port polygon. |
| `beneficial_owner_urn`  | string  |    yes   | Entity resolution link to the vessel's beneficial owner.                                                                             |
| `sanctioned_owner`      | boolean |    yes   | `true` when the beneficial owner appears on a sanctions list.                                                                        |

## Vessel types

The raw ITU vessel type code (0–99) is preserved in `metadata.itu_vessel_type_code`. Codex normalizes vessels into six categories for consistent filtering:

| Category         | Description                  |
| ---------------- | ---------------------------- |
| `container`      | Container ships              |
| `tanker_crude`   | Crude oil tankers            |
| `tanker_product` | Product and chemical tankers |
| `bulker`         | Dry bulk carriers            |
| `fishing`        | Fishing vessels              |
| `other`          | All other vessel types       |

## Navigation status codes

| Code | Label                      |
| ---- | -------------------------- |
| 0    | Under way using engine     |
| 1    | At anchor                  |
| 2    | Not under command          |
| 3    | Restricted maneuverability |
| 4    | Constrained by draught     |
| 5    | Moored                     |
| 7    | Engaged in fishing         |
| 8    | Under way sailing          |

<Note>
  AIS positions in the Codex dataset are compressed to one per minute per vessel. In Overwatch, live positions are kept at full resolution for 7 days and then [downsampled through progressive tiers](/overwatch/data-retention). Both raw and compressed views are available depending on your tier.
</Note>

## Join keys

| Key                    |  Presence | Notes                                                             |
| ---------------------- | :-------: | ----------------------------------------------------------------- |
| `record_id`            |   always  | APRS URN                                                          |
| `chunk_id`             |   always  | Deterministic from `record_id`                                    |
| `imo`                  |   often   | Primary vessel identity. Null for small craft without IMO numbers |
| `mmsi`                 |   always  | Fallback vessel identity                                          |
| `h3_index`             |   always  | H3 resolution-8 spatial key                                       |
| `port_event_id`        | sometimes | Links to Events Timeline for in-port positions                    |
| `beneficial_owner_urn` | sometimes | Entity resolution link to beneficial owner                        |

## Example query

Find vessels flagged as anomalous near a specific port in the last 30 days:

```sql theme={null}
SELECT
  record_id,
  vessel_name,
  imo,
  mmsi,
  timestamp,
  speed,
  nav_status,
  behavior_anomaly_flag,
  sanctioned_owner
FROM read_parquet('ais-maritime-2026-04.parquet')
WHERE h3_index = '88283082b9fffff'
  AND behavior_anomaly_flag = true
  AND timestamp >= now() - interval '30 days'
ORDER BY timestamp DESC;
```

## Known limitations

* `imo` is null for small craft, fishing vessels, and some flag-of-convenience registrations. Use `mmsi` as a fallback.
* `vessel_type` normalization collapses 99 ITU codes into 6 categories — check `metadata.itu_vessel_type_code` when you need the original classification.
* `beneficial_owner_urn` is populated by the entity resolution pipeline and may be null for recently ingested positions.
* Position compression (1-per-minute) means sub-minute maneuvers are not visible in the default view.