Skip to content
English
Support request Customer portal Sign in
Go to spire.com
  • There are no suggestions because the search field is empty.

Using API Query Parameters

Descriptions and examples of every available API parameter

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 :

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

Fields

Specifies AIS fields to return from AIS messages.

For example, to only return msg_type and mmsi:

Collection Type

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

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

Message Description

Only return messages of the msg_description specified.

For example, to only return static messages:

Message Type

MMSI

Only return messages with matching mmsi :

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 created_at  greater than or equal to the time specified:

Received Before

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

Vessels API Query Parameters

MMSI

Only return vessel(s) with matching mmsi:

IMO

Only return vessel(s) with matching imo:

NAME

Only return vessel(s) with search string present in the name:

Call Sign

Only return vessel(s) with matching call_sign:

Ship Type

Only return vessels with matching ship_type:

See help article Determining Ship Types for available values.

Class

Only return vessels with matching class:

Flag

Only return vessels with matching flag:

Updated After

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

Updated Before

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

Arriving After

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

Arriving Before

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

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 faq.spire.com.com contact Spire Sales Engineering for support using our client webform here