Message Filtering¶

AIS-catcher offers extensive filtering options to help you manage the volume and relevance of AIS data output. You can filter messages by type, MMSI, channel, and other criteria, allowing you to focus on the information most important to your use case. In addition, powerful downsampling tools such as unique message filtering, own-station interval, and position interval controls are available to further reduce redundant data and manage bandwidth or storage requirements, especially in high-traffic environments. These features make it easy to tailor the output to your needs, whether you are monitoring a busy port or running a resource-constrained installation.

Filtering Mesages types¶

To filter UDP, webviewer, TCP, MQTT, HTTP and screen output on message type, e.g. send only messages of type 1, 2, 3, 5, 18, 19, 24 and 27 over UDP:

AIS-catcher -u 127.0.0.1 10110 filter on allow_type 1,2,3,5,18,19,24,27

or remove message type 6 and 8:

AIS-catcher -u 127.0.0.1 10110 filter on block_type 6,8

Do not use spaces in the comma-separated message type list as it confuses the command line. Filtering will only take effect with the filter switched to ON (default OFF) and the filter needs to be defined per -u switch (or -H and -o).

In my home station, I am using this to control the size of the log file but still capture messages for inspection later. I am running with the command line parameter:

AIS-catcher -o 5 filter on block_type 1,2,3,4,5,9,18,19,21,24

Message type 8 is region-specific. If you encounter any messages in the wild that might be interesting for AIS-catcher to parse, please share in the Issue section and we can see if it is worthwhile to extend the JSON generator.

Message Downsampling¶

AIS-catcher provides several options to reduce the number of output messages by filtering or downsampling repeated or redundant data. This helps to minimize bandwidth, storage, or processing requirements, especially in high-traffic environments. The main downsampling options are:

Removing duplicates: `unique`¶

The unique or unique_interval option ensures that only unique messages are output within a specified time window. If a message with the same content (hash) is received multiple times within the interval, only the first is output, and duplicates are suppressed. This is useful for reducing repeated identical messages from the same source. Note that this is only relevant for stations aggregating from multiple sources with overlap.

Example:

AIS-catcher -o 1 unique on

Downsampling VDO messages: `own_interval`¶

The own_interval option controls the minimum interval (in seconds) between outputting messages from the receiver's own station (VDO messages). If multiple own-station messages are received within this interval, only the first is output. This is useful for reducing the frequency of self-reported position or status updates which can be quite frequent for certain devices.

AIS-catcher -O 123456789 -o 1 own_interval 10

Default is switched off:

AIS-catcher -O 123456789 -o 1 own_interval false

Downsampling position messages: `position_interval`¶

The position_interval option sets the minimum interval (in seconds) between outputting position reports (types 1, 2, 3, 18, and 27) for each MMSI. If multiple position messages for the same vessel are received within this interval, only the first is output. This helps to limit the rate of position updates for each vessel which are typically the most frequent messages.

AIS-catcher -u localhost 5012 position_interval 30

These options can be combined to fine-tune the output rate and avoid redundant data, depending on your use case and requirements.

Note: filtering for messages to screen can only be set on the command line and not in the JSON configuration file at this stage.

Filter settings¶

Generic filtering options requiring 'filter' set to 'true' or 'on' to be active:

Setting (JSON key / CLI setting name)	Type	Default	Description
filter	boolean	false	Enable/disable filtering
allow_type	list	all	Comma-separated list of message types to allow (1-27)
block_type	list	none	Comma-separated list of message types to block
allow_repeat	list	all	Allow messages with specific repeat counter values (0-3)
block_repeat	list	none	Block messages with specific repeat counter values
allow_mmsi	list	all	Only allow messages from specific MMSI numbers
block_mmsi	list	none	Block messages from specific MMSI numbers
allow_channel	string	all	Only allow messages from specific AIS channels
id	integer	all	Only allow messages from specific station IDs
gps	boolean	true	Include GPS messages in output
ais	boolean	true</

Downsampling options:

Setting (JSON key / CLI setting name)	Type	Default	Description
unique	boolean	false	Only send/show unique messages
position_interval	number	false	Minimal time in seconds between position updates for a ship, off = false or 0
own_interval	number	false	Minimal time in seconds between updates for own ship, off = false or 0