Overview

Below are all the available query parameters for the Messages and Vessels APIs.

  • Important Note: Be sure to include your query parameters in any API calls that include cursors, such as since or next so the filtered results persist through paginated responses.
  • API query parameters can be chained together. This is particularly helpful when you want to filter your results.
  • For query parameters able to take long lists (e.g. mmsi , imo ), we recommend keeping these lists below 400 items, otherwise you may encounter URI Too Long errors.

Messages API Query Parameters

Cleansed

Flag for returning cleansed or uncleansed messages in responses. By default, cleansed is true.

For uncleansed data, set cleansed to false :

GET https://ais.spire.com/messages?fields=decoded&cleansed=false

Fields

Specifies AIS fields to return from AIS messages.

For example, to only return msg_type and mmsi:

GET https://ais.spire.com/messages?fields=msg_type,mmsi

Collection Type

Only return messages with a specific collection_type: satellite or terrestrial.

For example, to only return satellite (S-AIS) messages:

GET https://ais.spire.com/messages?fields=decoded&collection_type=satellite

Message Description

Only return messages of the msg_description specified.

For example, to only return static messages:

GET https://ais.spire.com/messages?fields=decoded&msg_description=static

Message Type

GET https://ais.spire.com/messages?fields=decoded&msg_type=1,2,3

MMSI

Only return messages with matching mmsi :

GET https://ais.spire.com/messages?fields=decoded&mmsi=356206000,219657000,244992000

Position

Only return messages with position point within the specified polygon:

GET https://ais.spire.com/messages?fields=decoded&position={
        "type": "Polygon",
        "coordinates": [
          [
            [
              57.83203125,
              -37.43997405227057
            ],
            [
              105.1171875,
              -37.43997405227057
            ],
            [
              105.1171875,
              -8.928487062665504
            ],
            [
              57.83203125,
              -8.928487062665504
            ],
            [
              57.83203125,
              -37.43997405227057
            ]
          ]
        ]
      }

Received After

Only return messages with timestamp greater than or equal to the time specified:

GET https://ais.spire.com/messages?fields=decoded&received_after=2018-05-21T06:00:00

Received Before

Only return messages with timestamp less than or equal to the time specified (note: must be used in conjunction with received_after parameter):

GET https://ais.spire.com/messages?fields=decoded&received_after=2018-05-20T00:00:00&received_before=2018-05-20T23:59:59

Vessels API Query Parameters

MMSI

Only return vessel(s) with matching mmsi:

GET https://ais.spire.com/vessels?mmsi=219002418,244710824,244780327,457545000

IMO

Only return vessel(s) with matching imo:

GET https://ais.spire.com/vessels?imo=9799666,9363273,9180011

Call Sign

Only return vessel(s) with matching call_sign:

GET https://ais.spire.com/vessels?call_sign=LW 9897

Ship Type

Only return vessels with matching ship_type:

GET https://ais.spire.com/vessels/?ship_type=sailing

See help article Determining Ship Types for available values.

Class

Only return vessels with matching class:

GET https://ais.spire.com/vessels?class=B

Flag

Only return vessels with matching flag:

GET https://ais.spire.com/vessels/?flag=RU

Updated After

Only return vessels with an updated_at time greater than or equal to the time specified:

GET https://ais.spire.com/vessels/?updated_after=2018-05-21T17:00:00

Updated Before

Only return vessels with an updated_at time greater than or equal to the time specified:

GET https://ais.spire.com/vessels/?updated_before=2018-05-21T20:00:00

Arriving After

Only return vessels with an arriving_after time greater than or equal to the time specified:

GET https://ais.spire.com/vessels?arriving_after=2018-05-30T01:00:00

Arriving Before

Only return vessels with an arriving_before time less than or equal to the time specified:

GET https://ais.spire.com/vessels?arriving_before=2018-06-08T12:00:00

Last Known Position Within

Only return vessel(s) with last_known_position_within point within the specified polygon:

GET https://ais.spire.com/vessels/?last_known_position_within={
        "type": "Polygon",
        "coordinates": [
          [
            [
              57.83203125,
              -37.43997405227057
            ],
            [
              105.1171875,
              -37.43997405227057
            ],
            [
              105.1171875,
              -8.928487062665504
            ],
            [
              57.83203125,
              -8.928487062665504
            ],
            [
              57.83203125,
              -37.43997405227057
            ]
          ]
        ]
      }

Predicted Position Within

Only return vessel(s) with predicted_position_within point with the specified polygon:

GET https://ais.spire.com/vessels/?predicted_position_within={
        "type": "Polygon",
        "coordinates": [
          [
            [
              57.83203125,
              -37.43997405227057
            ],
            [
              105.1171875,
              -37.43997405227057
            ],
            [
              105.1171875,
              -8.928487062665504
            ],
            [
              57.83203125,
              -8.928487062665504
            ],
            [
              57.83203125,
              -37.43997405227057
            ]
          ]
        ]
      }

Last Known or Predicted Position Within

Only return vessel(s) with last_known_or_predicted_position_within point with the specified polygon or multipolygon:

GET https://ais.spire.com/vessels/?last_known_or_predicted_position_within={
        "type": "Polygon",
        "coordinates": [
          [
            [
              57.83203125,
              -37.43997405227057
            ],
            [
              105.1171875,
              -37.43997405227057
            ],
            [
              105.1171875,
              -8.928487062665504
            ],
            [
              57.83203125,
              -8.928487062665504
            ],
            [
              57.83203125,
              -37.43997405227057
            ]
          ]
        ]
      }
Did this answer your question?