Skylight Event Types

Part of the Skylight integration.

Overview

The Skylight integration brings maritime surveillance intelligence into EarthRanger. Events detected by Skylight — fishing activity, vessel rendezvous, speed anomalies, area entries and satellite detections — arrive as EarthRanger reports, so your team can monitor, triage and respond without switching platforms.

Each event is enriched with vessel information where available (name, MMSI, IMO, flag state, vessel type). Events involving two vessels, such as rendezvous, carry a second vessel block. Detections where no vessel identity is known arrive with the vessel fields empty — these are untracked or “dark” targets seen by satellite sensors.

Supported event types

EarthRanger event type Display title Skylight source type(s)
fishing_alert_rep Fishing fishing_activity_history
dark_rendezvous_alert_rep Dark Rendezvous dark_rendezvous
standard_rendezvous_alert_rep Standard Rendezvous standard_rendezvous
speed_range_alert_rep Speed Range speed_range
entry_alert_rep Marine Entry aoi_visit
detection_alert_rep Vessel Detection viirs, sar_sentinel1, eo_sentinel2, eo_landsat_8_9

Vessel Detection events come from four satellite sensors — Synthetic Aperture Radar (Sentinel-1), optical imagery (Sentinel-2 and Landsat 8/9) and nighttime lights (VIIRS) — and are distinguished by title: Dark Vessel Detection for unidentified targets, AIS Correlated Vessel Detection for detections matched to a known AIS-transmitting vessel.

What the fields show

  • Scores are percentages from 0 to 100: Fishing Score (%), Detection Score (%) and OSR Score (%).
  • Units are in the labels: knots (kn) for speeds, kilometres (km) for Speed Range distance and seconds (s) for durations.
  • Duration (s) on Standard Rendezvous, Dark Rendezvous and Fishing runs from the start of the event to its end.
  • On Marine Entry, Area of Interest names the area the vessel entered, and Hours In Area shows Pending while the vessel is still inside it; Time In Area (s) fills in once it leaves. Speed Range also shows the Area of Interest.
  • Owner and Authorizations come from Global Fishing Watch. Authorizations list the RFMO registries a vessel is authorized on, for example GFCM, ICCAT; about 3% of vessels have them. See Global Fishing Watch's data caveats.
Important

Create these event types before connecting Skylight. Until they exist, EarthRanger turns the events away with “You do not have permission to perform this action.”, and the Route Activity Logs show that message.

How to create these event types

1. Install the command-line tool and sign in

You need a terminal with Python 3.11 or newer and pipx installed, and an EarthRanger account on the target site. 

pipx install earthranger-cli                         # install the tool; this gives you the 'er' command

er profile add sitename --server sitename --username you   # save the site as a profile ('sitename' is the site's subdomain, e.g. 'grumeti' for grumeti.pamdas.org)
export ER_PROFILE=sitename                                 # tell 'er' to use that profile in this terminal
er auth login                                              # asks for your EarthRanger password and signs you in

Important: the account you log in with must have permissions on the Event Category that will host these event types.

2. Save this spec as skylight.yaml

Set category to the category that should host the Skylight events on this site (for example analyzer_event or monitoring).

The spec needs earthranger-cli 0.6.0 or newer. To update an existing install, run pipx upgrade earthranger-cli. 

category:
  value: analyzer_event
  display: Analyzer Event
event_types:
- value: standard_rendezvous_alert_rep
  display: Standard Rendezvous
  icon_id: skylight-standard-rendezvous_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 48
  ordernum: 1
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: duration
      label: Duration (s)
      type: number
    - key: entry_link
      label: More Information
      type: url
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Vessel 2 Information
    columns: 2
    fields:
    - key: vessel_1_name
      label: Vessel 2 Name
      type: string
    - key: vessel_1_display_country
      label: Vessel 2 Nationality
      type: string
    - key: vessel_1_mmsi
      label: Vessel 2 MMSI
      type: number
    - key: vessel_1_category
      label: Vessel 2 Category
      type: string
    - key: vessel_1_type
      label: Vessel 2 Vessel Type
      type: string
    - key: vessel_1_imo
      label: Vessel 2 IMO
      type: number
      column: right
    - key: vessel_1_length
      label: Vessel 2 Length (m)
      type: number
      column: right
    - key: vessel_1_owner_name
      label: Vessel 2 Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_1_authorizations
      label: Vessel 2 Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false
    - key: vessel_1_vessel_id
      label: Vessel 2 Vessel ID
      type: string
      active: false
    - key: vessel_1_track_id
      label: Vessel 2 Track ID
      type: string
      active: false
    - key: vessel_1_gfw_vessel_id
      label: Vessel 2 GFW Vessel ID
      type: string
      active: false
    - key: vessel_1_class
      label: Vessel 2 Class
      type: string
      active: false
    - key: vessel_1_country_filter
      label: Vessel 2 Flag (ISO3)
      type: string
      active: false
    - key: vessel_1_subcategory
      label: Vessel 2 Subcategory
      type: string
      active: false
- value: dark_rendezvous_alert_rep
  display: Dark Rendezvous
  icon_id: skylight-dark-rendezvous_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 48
  ordernum: 2
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: osr_score
      label: OSR Score (%)
      type: number
    - key: duration
      label: Duration (s)
      type: number
    - key: entry_link
      label: More Information
      type: url
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false
    - key: vessel_1_vessel_id
      label: Vessel 2 Vessel ID
      type: string
      active: false
    - key: vessel_1_name
      label: Vessel 2 Vessel Name
      type: string
      active: false
    - key: vessel_1_mmsi
      label: Vessel 2 MMSI
      type: number
      active: false
    - key: vessel_1_imo
      label: Vessel 2 IMO
      type: number
      active: false
    - key: vessel_1_category
      label: Vessel 2 Category
      type: string
      active: false
    - key: vessel_1_subcategory
      label: Vessel 2 Subcategory
      type: string
      active: false
    - key: vessel_1_class
      label: Vessel 2 Class
      type: string
      active: false
    - key: vessel_1_type
      label: Vessel 2 Vessel Type
      type: string
      active: false
    - key: vessel_1_country_filter
      label: Vessel 2 Flag (ISO3)
      type: string
      active: false
    - key: vessel_1_display_country
      label: Vessel 2 Flag Country
      type: string
      active: false
    - key: vessel_1_length
      label: Vessel 2 Length (m)
      type: number
      active: false
    - key: vessel_1_track_id
      label: Vessel 2 Track ID
      type: string
      active: false
    - key: vessel_1_gfw_vessel_id
      label: Vessel 2 GFW Vessel ID
      type: string
      active: false
- value: entry_alert_rep
  display: Marine Entry
  icon_id: skylight-entry_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 48
  ordernum: 3
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: aoi_name
      label: Area of Interest
      type: string
    - key: entry_speed
      label: Entry Speed (kn)
      type: string
    - key: exit_date
      label: Exit Date
      type: string
    - key: duration_in_area
      label: Hours In Area
      type: string
    - key: duration_in_area_seconds
      label: Time In Area (s)
      type: number
      column: right
    - key: entry_link
      label: More Information
      type: url
      column: right
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: entry_heading
      label: Entry Heading
      type: string
      active: false
    - key: end_heading
      label: Exit Heading
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false
- value: speed_range_alert_rep
  display: Speed Range
  icon_id: skylight-speed_range
  default_priority: amber
  auto_resolve: true
  resolve_time: 48
  ordernum: 4
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: aoi_name
      label: Area of Interest
      type: string
    - key: average_speed
      label: Average Speed (kn)
      type: number
    - key: distance
      label: Distance (km)
      type: number
    - key: duration
      label: Duration (s)
      type: number
    - key: entry_link
      label: More Information
      type: url
      column: right
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false
- value: detection_alert_rep
  display: Vessel Detection
  icon_id: skylight-detection-satellite_rep
  auto_resolve: true
  resolve_time: 48
  ordernum: 5
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: detection_type
      label: Detection Type
      type: string
    - key: correlated
      label: AIS Correlated
      type: boolean
    - key: data_source
      label: Sensor
      type: string
    - key: score
      label: Detection Score (%)
      type: number
    - key: image_url
      label: Image URL
      type: string
    - key: estimated_length
      label: Estimated Length (m)
      type: number
    - key: estimated_speed_kts
      label: Estimated Speed (kn)
      type: number
    - key: estimated_vessel_category
      label: Estimated Vessel Category
      type: string
    - key: heading
      label: Heading
      type: number
    - key: distance_to_coast_m
      label: Distance To Coast (m)
      type: number
      column: right
    - key: orientation
      label: Orientation
      type: number
      column: right
    - key: meters_per_pixel
      label: Meters Per Pixel
      type: number
      column: right
    - key: frame_ids
      label: Frame IDs
      type: string
      column: right
    - key: radiance_nw
      label: Radiance (nW)
      type: number
      column: right
    - key: entry_link
      label: More Information
      type: url
      column: right
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false
- value: fishing_alert_rep
  display: Fishing
  icon_id: skylight-fishing_rep
  default_priority: amber
  auto_resolve: true
  resolve_time: 48
  ordernum: 6
  sections:
  - label: Event Information
    columns: 2
    fields:
    - key: fishing_score
      label: Fishing Score (%)
      type: number
    - key: duration
      label: Duration (s)
      type: number
    - key: entry_link
      label: More Information
      type: url
    - key: created_at
      label: Published At
      type: string
      column: right
    - key: updated_at
      label: Updated At
      type: string
      column: right
  - label: Vessel Information
    columns: 2
    fields:
    - key: vessel_0_name
      label: Name
      type: string
    - key: vessel_0_display_country
      label: Nationality
      type: string
    - key: vessel_0_mmsi
      label: MMSI
      type: string
    - key: vessel_0_category
      label: Category
      type: string
    - key: vessel_0_type
      label: Vessel Type
      type: string
    - key: vessel_0_imo
      label: IMO
      type: number
      column: right
    - key: vessel_0_length
      label: Length (m)
      type: number
      column: right
    - key: vessel_0_owner_name
      label: Owner
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Owner'
      column: right
    - key: vessel_0_authorizations
      label: Authorizations
      type: string
      description: 'Source: Global Fishing Watch, via Skylight: https://api.skylight.earth/docs/#definition-VesselV2Authorization'
      column: right
  - label: Hidden
    active: false
    fields:
    - key: event_id
      label: Skylight Event ID
      type: string
      active: false
    - key: vessel_0_vessel_id
      label: Vessel ID
      type: string
      active: false
    - key: vessel_0_track_id
      label: Track ID
      type: string
      active: false
    - key: vessel_0_gfw_vessel_id
      label: GFW Vessel ID
      type: string
      active: false
    - key: vessel_0_class
      label: Class
      type: string
      active: false
    - key: vessel_0_country_filter
      label: Flag (ISO3)
      type: string
      active: false
    - key: vessel_0_subcategory
      label: Subcategory
      type: string
      active: false

3. Preview, then apply

er events apply skylight.yaml --dry-run   # shows what will be created or changed
er events apply skylight.yaml             # actually does it

Applying is safe to repeat: it creates what is missing and patches only what differs. Nothing is ever deleted.

4. Verify

er events show event-type detection_alert_rep

 

CLI tool and full spec documentation: https://github.com/PADAS/earthranger-cli