Events Timeline schema

The Events Timeline is the unified event stream that connects every Axiom product. It contains ~1.7M events from 16+ source normalizers covering permits, council votes, AIS dark events, port calls, regulatory filings, POI lifecycle changes, crop health alerts, and more. Every other Codex dataset references an event_id from this timeline, making it the graph spine across the catalog. Records are ingested continuously and published as monthly immutable snapshots. Every record inherits the full APRS envelope and carries the join keys documented below.

Dataset-specific fields

Field	Type	Nullable	Description
`event_type`	dotted string	no	Hierarchical event type. See event taxonomy.
`event_category`	enum	no	High-level grouping: `maritime`, `civic`, `regulatory`, `poi`, `environmental`, `economic`, `risk`.
`entity_id`	string	no	Canonical key for the affected entity. Shape depends on `entity_type`.
`entity_type`	enum	no	Type of the affected entity. See entity types.
`entity_name`	string	yes	Human-readable name (display only).
`location`	PostGIS Point	yes	WGS84 geometry. Use `h3_index` for joins.
`location_name`	string	yes	Human-readable location description.
`h3_index`	string	yes	H3 resolution-8 cell derived from `location`.
`started_at`	timestamptz	no	When the real-world event began.
`resolved_at`	timestamptz	yes	When the event closed. Null if still open or point-in-time.
`magnitude`	float	yes	Event-specific magnitude. Unit varies by `event_type`. See magnitude units.
`confidence`	float [0,1]	yes	Pipeline confidence that the event is real.
`source`	string	no	Originating pipeline (`aisstream`, `socrata`, `granicus`, etc.).
`source_ref`	string	yes	Source-native reference for re-fetch.
`product`	enum	no	Generating product: `locus`, `overwatch`, or `codex`.
`downstream_outcome`	string	yes	Post-hoc outcome annotation from cascade detectors.
`outcome_lag_days`	integer	yes	Days between this event and its downstream outcome.
`metadata`	JSONB	yes	Event-specific overflow fields. See metadata keys.
`jurisdiction_slug`	string	yes	Populated for civic and regulatory events.

Event taxonomy

Event types use a {domain}.{verb} convention. You can filter at the family level (event_type LIKE 'port.%') or by specific action.

Maritime events

Type	Description
`port.entered`	Vessel crossed port polygon inbound
`port.anchored`	Vessel reported anchored status inside port
`port.berthed`	Vessel matched to a specific berth
`port.departed`	Vessel crossed port polygon outbound
`visit.in_progress`	Open vessel visit, no departure yet
`visit.completed`	Paired entry and departure. `magnitude` = visit duration in hours
`dark_event`	AIS gap plus kinematic violation
`satellite.{alert_type}`	Per-alert-type subtype (e.g., `vessel_cluster`, `dark_emission`)

Civic events

Type	Description
`council.approved`	Council vote in favor
`council.denied`	Council vote against
`council.tabled`	Motion tabled or deferred
`council.mentioned`	Topic mentioned, no decision
`permit.filed`	New permit application
`permit.approved`	Permit approved
`permit.denied`	Permit denied
`permit.expired`	Permit aged out without completion
`permit.completed`	Work finaled
`permit.cancelled`	Withdrawn by applicant
`permit.revoked`	Revoked by authority
`noise_complaint`	311 noise complaint
`business_license`	New license issued

Regulatory events

Type	Description
`regulatory.filing`	SEC 8-K, 10-K, etc.
`regulatory.enforcement`	FDA, EPA, or OSHA action
`regulatory.complaint`	Consumer or worker complaint filing
`regulatory.notice`	Authority notice
`regulatory.rule`	Final rule publication

POI events

Type	Description
`poi.opened`	First observation of a new POI
`poi.active`	Ongoing POI observation
`poi.temporarily_closed`	Temporary closure
`poi.closed`	Permanently closed

Environmental events

Type	Description
`environmental.disaster`	FEMA/NWS disaster declaration
`crop.ndvi_drop`	Sentinel-2 NDVI decline. `magnitude` = percent change
`crop.ndvi_recovery`	NDVI recovery
`river.{status}`	Gauge status subtype (`flood`, `action`, `normal`)

Economic events

Type	Description
`jobs.snapshot`	Periodic snapshot of active postings per cell. `magnitude` = listing count
`migration.inflow`	Net positive migration. `magnitude` = net persons
`migration.outflow`	Net negative migration
`trade.{flow_type}`	Customs/CBP trade flow subtype

Risk events

Type	Description
`risk.critical`	Risk score >= 85
`risk.elevated`	Risk score >= 60
`risk.moderate`	Risk score >= 30
`risk.low`	Risk score < 30

Entity types

The shape of entity_id depends on entity_type:

Entity type	`entity_id` shape	Example
`vessel`	IMO number (preferred) or MMSI	`9432871`
`parcel`	`{jurisdiction_slug}:{parcel-number}`	`philadelphia-pa:12-345-678`
`permit`	`permit:{jurisdiction}:{permit-id}`	`permit:sf-ca:2024-0412`
`council_matter`	`legistar:{jurisdiction}:{matter-id}`	`legistar:phila-pa:24-0031`
`poi`	`urn:aprs:record:poi:{source}:{id}`	`urn:aprs:record:poi:fsq:abc123`
`organization`	`urn:aprs:entity:company:{id}`	`urn:aprs:entity:company:acme-llc`
`person`	`urn:aprs:entity:person:{id}`	`urn:aprs:entity:person:j-doe`
`h3_cell`	H3 resolution-8 string	`88283082b9fffff`
`jurisdiction`	`jurisdiction_slug`	`philadelphia-pa`

Magnitude units

magnitude is polymorphic — its unit depends on event_type. Always check event_type before comparing magnitude values.

Event type pattern	Unit
`visit.completed`	Hours (visit duration)
`dark_event`	Hours (AIS gap)
`crop.ndvi_*`	Percent change vs. 5-year baseline
`jobs.snapshot`	Count of active postings
`migration.*`	Net persons
`trade.*`	USD value (notional)
`risk.*`	Risk score 0–100
`permit.*` (with `metadata.declared_value`)	USD value

Metadata keys

The metadata JSONB column holds type-specific fields. Keys are version-bound — a key present in one event type is not guaranteed in another.

Key	Event types	Description
`kinematic_meta`	`dark_event`	Implied speed, Froude limit, OU max reach, actual distance, failed tests
`psc_detention_history`	Maritime events	Port State Control detentions linked to this event
`declared_value`	`permit.*`	USD value declared on the permit
`voting_tally`	`council.*`	`{yes, no, abstain, absent}`
`alert_type_raw`	`satellite.*`	Upstream alert code
`related_event_ids`	Any	Array of `event_id` UUIDs this event is linked to. See event chains
`mmsi`	Maritime	MMSI when `entity_type='vessel'`
`imo`	Maritime	IMO number when known
`parcel_id`	Civic (permits/zoning)	Parcel identifier

Event chains

Events are often cascading effects of earlier events. The metadata.related_event_ids field links events into chains:

Maritime dark event chain: port.departed → dark_event → port.entered (different port)
Permit cascade: council.approved → permit.filed → permit.approved → permit.completed
Risk cascade: regulatory.enforcement → risk.critical

Traversal example

Find every downstream civic event following a dark event within 12 months:

WITH RECURSIVE chain AS (
  SELECT id, event_type, started_at, metadata
  FROM codex.events_timeline
  WHERE id = 'c5a8e4f2-9b7d-4c1e-b3a5-1f2d8c0e7a93'

  UNION ALL

  SELECT e.id, e.event_type, e.started_at, e.metadata
  FROM codex.events_timeline e
  JOIN chain c
    ON c.id::text = ANY(
      ARRAY(SELECT jsonb_array_elements_text(e.metadata->'related_event_ids'))
    )
  WHERE e.started_at - c.started_at BETWEEN interval '0' AND interval '365 days'
)
SELECT * FROM chain
WHERE event_category = 'civic';

Confidence semantics

The confidence field represents pipeline confidence that the event is real, not a downstream prediction score:

Maritime — AIS signal quality × kinematic model posterior
Civic — LLM extraction confidence × source reliability score
Regulatory — 1.0 for primary-source filings; degraded for secondary mirrors
Environmental — satellite cloud cover × model confidence

Events with confidence < 0.4 are excluded from Research and Commercial tier exports by default.

Join keys

Key	Presence	Notes
`event_id` (= `id`)	always	Primary key — the spine across all Codex datasets
`record_id`	always	APRS URN: `urn:aprs:record:event:{product}:{id}`
`chunk_id`	always	Deterministic from `record_id`
`h3_index`	often	Null for events without geometry (e.g., regulatory filings)
`jurisdiction_slug`	often	Always for civic and regulatory; sometimes for others
`mmsi`	maritime only	In `metadata.mmsi`
`imo`	maritime only	In `metadata.imo` (preferred over MMSI)
`parcel_id`	civic only	In `metadata.parcel_id`
`entity_urn`	often	Present for person, organization, and POI entities

Example queries

Permit cascades after approved rezonings

SELECT
  rez.id             AS rezoning_event_id,
  rez.jurisdiction_slug,
  rez.started_at     AS rezoning_date,
  permit.event_type  AS permit_stage,
  permit.started_at  AS permit_date,
  permit.started_at - rez.started_at AS lag
FROM codex.events_timeline rez
JOIN codex.events_timeline permit
  ON permit.metadata->'related_event_ids' ? rez.id::text
WHERE rez.event_type = 'council.approved'
  AND rez.started_at >= now() - interval '1 year'
  AND permit.event_type LIKE 'permit.%'
ORDER BY rez.jurisdiction_slug, rez.started_at;

All dark events longer than 48 hours

SELECT
  entity_name,
  started_at,
  resolved_at,
  magnitude AS gap_hours,
  metadata->'kinematic_meta'->>'implied_speed_kn' AS implied_speed
FROM read_parquet('events-timeline-2026-04.parquet')
WHERE event_type = 'dark_event'
  AND magnitude > 48
ORDER BY magnitude DESC;

Known limitations

entity_id shape is polymorphic — you must branch on entity_type before joining.
magnitude units vary by event type. See magnitude units before comparing.
related_event_ids coverage is uneven. Currently populated by maritime and permit normalizers; civic cascade linking is in progress.
downstream_outcome is post-hoc and sparse — only populated once cascade detectors run, which can take 30–90 days.

Get started

Frameworks

Reference

Dataset-specific fields

Event taxonomy

Maritime events

Civic events

Regulatory events

POI events

Environmental events

Economic events

Risk events

Entity types

Magnitude units

Metadata keys

Event chains

Traversal example

Confidence semantics

Join keys

Example queries

Permit cascades after approved rezonings

All dark events longer than 48 hours

Known limitations

​Dataset-specific fields

​Event taxonomy

​Maritime events

​Civic events

​Regulatory events

​POI events

​Environmental events

​Economic events

​Risk events

​Entity types

​Magnitude units

​Metadata keys

​Event chains

​Traversal example

​Confidence semantics

​Join keys

​Example queries

​Permit cascades after approved rezonings

​All dark events longer than 48 hours

​Known limitations

Dataset-specific fields

Event taxonomy

Maritime events

Civic events

Regulatory events

POI events

Environmental events

Economic events

Risk events

Entity types

Magnitude units

Metadata keys

Event chains

Traversal example

Confidence semantics

Join keys

Example queries

Permit cascades after approved rezonings

All dark events longer than 48 hours

Known limitations