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

Land Filter

Part of the AIS data cleansing implemented by Spire as default (cleansed=true) is to filter out AIS positions messages that are on land. While all data cleansing in Messages API is turned on by default, if needed the land filter can be enabled or disabled independently from other cleansing
To exclude land filtering of positions set land_filter to false, to explicitly include land filtering set land_filter to true

GET https://ais.spire.com/messages?fields=decoded&land_filter=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
            ]
          ]
        ]
      }

Enable Enhanced Vessel Data (EVD)

Simply include embed=enhanced_data  as a query parameter within a Vessels API call to return EVD fields:
GET https://ais.spire.com/vessels?embed=enhanced_data 

For applicable vessels, EVD will be appended to the vessel record. (If we don't have a value for the field, null is returned.)
Full examples of EVD data are found here 

For questions about Spire Sense data services not found in answers.spire.com contact cx@spire.com 

Did this answer your question?