Need help with ambient-shipping?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

411 Stars 27 Forks 5 Commits 2 Opened issues


This repo contains utilities for capturing AIS messages and joining them with shipping records.

Services available


Need anything else?

Contributors list

# 381,905
2 commits

Ambient Shipping

This repo contains utilities for capturing AIS messages broadcast by passing ships and then joining them with public data sets that reveal what the ships are carrying.


Ambient Shipping enables you to look inside cargo ships. It has two main components:

    : A simple set of functions that enables (1) the translation between an MMSI and a Vessel's Name and (2) wrappers around the Enigma Public API to query Bill of Lading Import Records for that Vessel to reveal what is inside it.
    : A data relay server for relaying decoded AIS transmissions to a remote database server. It is intended to be run on a small linux machine with a SDR (e.g. a raspberry pi) and in proximity to waterways frequented by cargo ships.

NY Harbor


The Automatic Identification System (AIS) is a broadcast radio signal that reports a ship's position, speed, heading and other metadata about its movements. It is primarily used for safety and for ships to have situational awareness. The signals are broadcast on two VHF channels (161.975 MHz, 162.025 MHz) and generally have a range of 10-20 miles at sea, although, on land, buildings interfere with the signal and it can be difficult to receive without a clear line of sight for the antenna.

AIS Transceiver

There are many different types of AIS messages that are broadcast (detailed here) but, most commonly, an AIS transceiver sends basic positional data every 2 to 10 seconds depending on a vessel's speed while underway, and every 3 minutes while a vessel is at anchor.

Using a RTL-SDR dongle, these transmissions can be picked up and decoded. The RTL-AIS project is quite useful as a local server which will receive AIS messages and output them on a local host port. It must be run as a background process for
to function properly.

Example AIS data:

!AIVDM,1,1,,B,15MwDp0P0hJe>pLGBUq;[email protected],0*27


The spec for AIS encoding is quite complicated, but convenient tools like Python's libais make it straightforward to decode. Using this in conjunction with the
script will enable received messages to be uploaded to a remote database for later analysis.

For instance, a decoded AIS message will look something like this:

print ais.decode('15PIIv7P00D5i9HNn2Q3G?wB0t0I')
(nb the last portion of the message is the payload to be decoded. see the AIS spec for a fuller explanation.)

The MMSI field contains the ship's Maritime Mobile Service Identity number. The MMSI is a unique identifier for the ship's radio that can be used to communicate directly with the ship. MMSIs are regulated and managed internationally by the International Telecommunications Union in Geneva, Switzerland, just as radio call signs are regulated.

Bill of Lading

contains a function for looking up the MMSI with the ITU in order to find out the Vessel Name (you can also get the Vessel's satellite phone number if you're interested in giving them a call). If the ship is transporting containers or other commodities, the Vessel Name can be used to query the Enigma Public API to discover what the ship contains.

The script relies upon data published in the Automated Manifest System by the US Customs and Border Protection. It contains structured copies of the bills of lading of everything that is imported into the United States. A bill of lading is a document that describes a shipment: who sent it, where its going, what it contains, &c.


Ambient Shipping grew out of a residency of the More&More Unlimited collective on Governor's Island in collaboration with Surya Mattu, Sarah Rothberg and Marina Zurkow and it was made possible with support from the Lower Manhattan Cultural Council. More&More Unlimited produces critical and artistic work engaging with the impact of maritime shipping on deep oceans and the logistics of global trade.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.