Skip to main content

Fundamentals


Making a Request - Queries#

To access the data through the Spire Maritime 2.0 API, you will need to execute a GraphQL query. This query essentially asks for specific fields on one or more objects; in other words, a GraphQL query describes the shape of your data "graph".

A query is generally structured based on the following outline:

query {
query_object_name(
argument_1: <value>
...
argument_n: <value>
) {
output_field_1
...
output_field_n
}
}

Available Queries#

QueryUse case
vesselsGet static vessel data and some enhanced data
predictedVesselRouteGet predicted routing details for a vessel
portGiven a UNLOCODE, get port latitude, longitude and name
matchedPortGiven a string such as port name, get the matching port UNLOCODE and other port data

Supported Types#

More information about the GraphQL type system can be found here.

Default Scalar Types#

Scalar TypeDescription
BooleanThe Boolean scalar type represents true or false.
FloatThe Float scalar type represents signed double-precision fractional values as specified by IEEE 754.
IntegerThe Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
StringThe String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
IDThe ID scalar type represents a unique identifier, often used to fetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.
IMO Vessel's IMO number
MMSI Vessel's MMSI number
DateTimeA date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
GeoJsonPositionRepresents a pair of coordinates in a decimal format [number, number]
WKTGeometry in a Well-Known Text format.
UNLOCODEUN/LOCODE as defined by the UNECE.

TimeDuration field#

We defined the TimeDuration field to represent the time duration in various formats. The type has 3 properties each representing a different format:

  • iso - Represents duration in ISO 8601 format; e.g. PT24H5M30S represents 24 hours, 5 minutes, 30 seconds.
  • seconds - Represents duration in seconds
  • text - represents duration in human-readable text, e.g. 1h1m45s

GraphQL Object Types#

These object types were developed by Spire to accommodate our unique data. Definitions of each GraphQL object type can be found in the Output section of the Fundamentals page.


vessels Query Arguments#

All arguments for the vessels query:

vessels(
after: String
areaOfInterest: AreaOfInterest
callsign: [String!]
first: Int = 100
flag: [String!]
imo: [IMO!]
lastPositionUpdate: TimeRange
mmsi: [MMSI!]
name: [String!]
shipType: [ShipType!]
): VesselConnection!

More information about the GraphQL Object Types of the arguments fields can be found below. All fields should resolve to a scalar type, outlined in the Default Scalar Types section above. For further details about all the fields can be found in the Data Dictionary section.

areaOfInterest#

If provided, only vessels with their most recent position being within the area of interest defined by the polygon will be returned.

The area of interest is either a GeoJSON object or a WKT string; in either case representing a closed polygon. It is an error to set both the geoJson and wkt fields, or to set neither.

type AreaOfInterest {
polygon: GeoJsonPolygonInput
wkt: WKT
}

GeoJson#

GeoJSON object specifying polygon area of interest.

type GeoJson {
coordinates: [[GeoJsonPosition!]!]!
type: String!
}

coordinates#

Polygon geometry in GeoJSON format.

wkt#

Geometry in a Well-Known Text format.

TimeRange#

If provided, only vessels having their most recent position update time within the provided time range will be returned.

type TimeRange {
endTime: DateTime
startTime: DateTime!
}

endTime

Timestamp of the end of the time range (ISO 8601 format); if omitted, the current time is used.

startTime

Timestamp of the beginning of the time range (ISO 8601 format).

shipType#

Only return vessels having one of the provided vessel types. ShipType must be specified in all capital letters.

Valid shipTypes are shown in the table below:

shipTypeShip Type Name
CAR_CARRIERCar Carrier
COMBINATION_CARRIERCombination Carrier
CONTAINERContainer
DRY_BULKDry Bulk Cargo
FISHINGFishing
GAS_CARRIERGas Carrier
GENERAL_CARGOGeneral Cargo
GENERAL_TANKERGeneral Tanker
LIVESTOCKLivestock Carrier
LNG_CARRIERLNG Carrier
OFFSHOREOffshore Vessel
OTHEROther
REEFERReefer Cargo
ROLL_ON_ROLL_OFFRoll-on Roll-off Cargo
TANKER_CHEMICALSTanker - Chemicals
TANKER_CRUDETanker - Crude
TANKER_PRODUCTTanker - Product Tanker
TUGTug
VEHICLE_PASSENGERVehicle/Passenger

More information about the GraphQL Object Types of the output fields can be found below. All fields should resolve to a scalar type, outlined in the Default Scalar Types section above. For further details about all the fields can be found in the Data Dictionary section.

vessels Output#

Combined vessel, voyage, and position object. All values represent the latest information available on the vessel. See this link for more details on the field meanings.

type Vessel {
currentVoyage: Voyage
id: ID!
lastPositionUpdate: lastPositionUpdate
staticData: VesselStaticData!
updateTimestamp: DateTime
}

Voyage#

type Voyage {
destination: String
draught: Float
eta: DateTime
matchedPort: MatchedPort
timestamp: DateTime
updateTimestamp: DateTime
}

MatchedPort

Port matched based on destination.

type MatchedPort {
matchScore: Float!
port: Port
}

Port

Matched port with the best confidence value.

type Port {
centerPoint: GeoPoint
name: String!
unlocode: UNLOCODE!
}

GeoPoint

Port central point.

type GeoPoint {
latitude: Float!
longitude: Float!
}

lastPositionUpdate#

Latest vessel position update.

type lastPositionUpdate{
accuracy: AisAccuracy
collectionType: PositionCollectionType
course: Float
heading: Float
latitude: Float
longitude: Float
maneuver: AisManeuverIndicator
navigationalStatus: AisNavigationStatus
rot: Float
speed: Float
timestamp: DateTime
updateTimestamp: DateTime
}

AisAccuracy

Vessel position accuracy flag. The position accuracy flag indicates the accuracy of the fix.

enum AisAccuracy {
HIGH
Indicates a DGPS-quality fix with an accuracy of < 10ms
LOW
Default accuracy, indicates an unaugmented GNSS fix with accuracy > 10m
}

PositionCollectionType

Data source of position update.

enum PositionCollectionType {
DYNAMIC
SATELLITE
TERRESTRIAL
}

AisManeuverIndicator

Vessel special maneuver indicator.

enum AisManeuverIndicator {
ENGAGED_IN_SPECIAL_MANEUVER
Special maneuver (such as regional passing arrangement)
NOT_AVAILABLE
Not available (default)
NOT_ENGAGED_IN_SPECIAL_MANEUVER
No special maneuver
}

AisNavigationStatus

Navigational Status in an AIS message. See our FAQ for more details: https://faq.spire.com/how-to-interpret-navigational-status.

AisNavigationStatus ValueDescription
AGROUND6 : Aground
AIS_SART_IS_ACTIVE14 : Any of the following are active: AIS-SART (Search and Rescue Transmitter), AIS-MOB (Man Overboard), AIS-EPIRB (Emergency Position Indicating Radio Beacon)
AT_ANCHOR1 : Anchored
CONSTRAINED_BY_HER_DRAUGHT4 : Ship draught is limiting its movement
ENGAGED_IN_FISHING7 : Engaged in fishing
MOORED5 : Moored (tied to another object to limit free movement)
NOT_DEFINED_DEFAULT15 : Undefined (default)
NOT_UNDER_COMMAND2 : Not under command
POWER_DRIVEN_VESSEL_PUSHING_AHEAD_TOWING_ALONGSIDE12 : Power-driven vessel pushing ahead/towing alongside
POWER_DRIVEN_VESSEL_TOWING_ASTERN11 : Power-driven vessel towing astern
RESERVED_FOR_FUTURE_AMENDMENT_OF_NAVIGATIONAL_STATUS_FOR_HSC9 : Number reserved for modifying reported status of ships carrying dangerous goods/harmful substances/marine pollutants
RESERVED_FOR_FUTURE_AMENDMENT_OF_NAVIGATIONAL_STATUS_FOR_WIG10 : Number reserved for modifying reported status of ships carrying dangerous goods/harmful substances/marine pollutants
RESERVED_FOR_FUTURE_USE13 : Reserved for future use
RESTRICTED_MANEUVERABILITY3 : Has restricted maneuverability
UNDER_WAY_SAILING8 : Under way sailing
UNDER_WAY_USING_ENGINE0 : Under way using its engine

VesselStaticData#

Vessel static information.

type VesselStaticData {
aisClass: AisClass
callsign: String
dimensions: VesselDimensions
flag: String
imo: IMO
mmsi: MMSI
name: String
shipSubType: ShipSubType
shipType: ShipType
timestamp: DateTime
updateTimestamp: DateTime
}

AisClass

Vessel AIS class, A or B.

enum AisClass {
A
AIS information from a class A transponder
B
AIS information from a class B transponder
}

VesselDimensions

Vessel Dimensions.

type VesselDimensions {
a: Int
b: Int
c: Int
d: Int
length: Int
width: Int
}

ShipSubType

Subtype of the ship and cargo. Valid values are listed in the table below.

shipSubTypeShip Type Name
AGGREGATES_CARRIERGeneral Cargo: Aggregates Carrier
ALUMINIUM_CARRIERDry Bulk: Aluminium Carrier
BITUMEN_CARRIERGeneral Cargo: Bitumen Carrier
CABU_CARRIERDry Bulk: Bulk/Caustic Soda Carrier (CABU)
CARBON_DIOXIDEGeneral Tanker: Carbon Dioxide Tanker
CAR_CARRIERCar Carrier
CEMENT_CARRIERDry Bulk: Cement Carrier
COALDry Bulk: Coal Carrier
COMBINATION_CARRIERCombination Carrier
CONTAINERContainer
CONTAINER_BULKDry Bulk: Container Bulk Carrier
CONTAINER_REEFERContainer: Reefer
DECK_CARGOGeneral Cargo: Deck-Cargo
DRY_BULKDry Bulk: Dry Bulk Carrier
EFFLUENT_TANKERGeneral Tanker: Effluent Tanker
FISHINGFishing
FISH_CARRIERGeneral Cargo: Fish Carrier
GENERAL_TANKERGeneral Tanker
GREAT_LAKESDry Bulk: Great Lakes Carrier
GYPSUM_CARRIERDry Bulk: Gypsum Carrier
HEAVY_LIFTGeneral Cargo: Heavy Lift
HEAVY_LIFT_SEMI_SUBMERSIBLEGeneral Cargo: Heavy Lift - Semi Submersible
LIMESTONE_CARRIERDry Bulk: Limestone Carrier
LIVESTOCKLivestock Carrier
LNG_CARRIERGas Carrier: LPG Carrier
LOGSGeneral Cargo: Logs
LOG_CARRIERDry Bulk: Log Carrier
LPG_CARRIERLNG Carrier
LUMBER_CARRIERDry Bulk: Lumber Carrier
MISCELLANEOUSGeneral Cargo: Miscellaneous
MOLASSES_CARRIERGeneral Tanker: Molasses Carrier
MULTI_PURPOSE_CARRIERGeneral Cargo: Multi-purpose Carrier
nullNo vessel subtype
NUCLEAR_FUEL_CARRIERGeneral Cargo: Nuclear Fuel Carrier
OFFSHOREOffshore Vessel
OPEN_HATCHDry Bulk: Open Hatch Carrier
ORE_BULK_OIL_CARRIERCombination Carrier: Ore/Bulk/Oil Carrier
ORE_CARRIERDry Bulk: Ore Carrier
ORE_OIL_CARRIERCombination Carrier: Ore/Oil Carrier
OTHEROther
PALLET_CARRIERGeneral Cargo: Pallet Carrier
PROBOGeneral Tanker: PROBO Tanker
REEFERReefer Cargo
REPLENISHMENTGeneral Tanker: Replenishment
ROLL_ON_ROLL_OFFGeneral Cargo: Roll-on Roll-off
SEA_RIVER_TYPEGeneral Cargo: Sea River Type
SELF_DISCHARGINGSelf Discharging
SLOPSGeneral Tanker: Slops
STONE_CARRIERGeneral Cargo: Stone Carrier
TANKER_CHEMICALSTanker - Chemicals
TANKER_CRUDETanker - Crude
TANKER_PRODUCTTanker - Product Tanker
TUGTug
TWEEN_DECKERGeneral Cargo: Tween Decker
VEG_OIL_CARRIERGeneral Tanker: Vegetable Oil Carrier
VEHICLE_PASSENGERVehicle/Passenger
WATER_CARRIERGeneral Tanker: Water Carrier
WINE_CARRIERGeneral Tanker: Wine Carrier
WOOD_CHIP_CARRIERDry Bulk: Wood Chip Carrier
WOOD_PULPDry Bulk: Wood Pulp Carrier

ShipType

Only return vessels having one of the provided vessel types. ShipType must be specified in all capital letters.

Valid shipTypes are shown in the table below:

shipTypeShip Type Name
CAR_CARRIERCar Carrier
COMBINATION_CARRIERCombination Carrier
CONTAINERContainer
DRY_BULKDry Bulk Cargo
FISHINGFishing
GAS_CARRIERGas Carrier
GENERAL_CARGOGeneral Cargo
GENERAL_TANKERGeneral Tanker
LIVESTOCKLivestock Carrier
LNG_CARRIERLNG Carrier
OFFSHOREOffshore Vessel
OTHEROther
REEFERReefer Cargo
ROLL_ON_ROLL_OFFRoll-on Roll-off Cargo
TANKER_CHEMICALSTanker - Chemicals
TANKER_CRUDETanker - Crude
TANKER_PRODUCTTanker - Product Tanker
TUGTug
VEHICLE_PASSENGERVehicle/Passenger

pageInfo Output#

Information about pagination in a connection.

type PageInfo {
endCursor: String
hasNextPage: Boolean!
}

totalCount Output#

Information about the amount of results in a query. The indicated value might be a lower bound if the total isn't known when there are too many results.

type ResultCount {
relation: ResultCountRelation!
value: Int!
}

ResultCountRelation

enum ResultCountRelation {
EQUAL
LOWER_OR_EQUAL
}

vessels Data Dictionary#

Spire Maritime 2.0 API includes the highest-level information about a ship in our vessels database. The information contained here is a combination of data from AIS messages and external data sources. The records within provide an up-to-date snapshot of the ship when possible.

Argument / OutputFieldType or Object NameDescription
ArgumentafterstringWhen paging through results, returns the elements in the result set that come after the specified cursor. The value of the after argument can be obtained from pageInfo.endCursor. See more about cursor-based pagination here.
ArgumentareaOfInterestAreaOfInterestThe area of interest is either a GeoJSON object or a WKT string; in either case representing a closed polygon. It is an error to set both the geoJson and wkt fields, or to set neither. If provided, only vessels with their most recent position being within the area of interest defined by the polygon will be returned.
ArgumentpolygonGeoJsonPolygonInputPolygon geometry in GeoJSON format.
ArgumentcoordinatesGeoJsonPositionPolygon coordinates in format [[[number, number]...]...]
ArgumenttypestringMust be "Polygon"
ArgumentwktstringRepresents linestring geometry in Well-Known Text
Argument / OutputcallsignstringVessel call sign - Only return vessels having one of the provided call signs.
ArgumentfirstintegerMaximum number of records to return. The default is 100 and valid values are 1–1000. Anything less than 1 is converted to the default. Anything greater than the maximum is converted to the maximum. Due to how matches are collected, the number of records returned may be less than this value even when there are more matches in the total result set. In other words, use only the pageInfo.hasNextPage property in the response metadata to determine whether to fetch more results, do not test whether the number of records returned is less than this value.
Argument / OutputflagstringOnly return vessels sailing under one of the provided countries. The countries must be provided as ISO 3166 alpha-2 codes. Flag string must be capitalized in argument.
Argument / OutputimointegerVessel unique International Maritime Organization number
ArgumentlastPositionUpdateTimeRangeIf provided, only vessels having their most recent position update time within the provided time range will be returned.
ArgumentendTimeDateTimeTimestamp of the end of the time range (ISO 8601 format); if omitted, the current time is used.
ArgumentstartTimeDateTimeTimestamp of the beginning of the time range (ISO 8601 format).
Argument / OutputmmsiintegerVessel Maritime Mobile Service Identity
Argument / OutputnamestringVessel name. When using this as an argument, the vessel name must be an exact match, but it is case insensitive (meaning the name does not have to be in all capital letters).
Argument / OutputshipTypeShipTypeCategory of vessel. Only return vessels having one of the provided vessel types. See shipType in the Output section for the ShipType enumeration details.
OutputnodesVesselCombined vessel, voyage and position object. All values represent the latest information available for the vessel. See this link for more details on the field meanings.
OutputcurrentVoyageVoyageLatest/current vessel voyage
OutputidIDSpire internal vessel identifier.
OutputlastPositionUpdatelastPositionUpdateLatest vessel position update.
OutputaccuracyAisAccuracyVessel position accuracy flag. The position accuracy flag indicates the accuracy of the fix.
OutputcollectionTypePositionCollectionTypeData source of position update. Three possible values: DYNAMIC, SATELLITE, TERRESTRIAL.
OutputcoursefloatVessel course
OutputheadingfloatVessel directional heading (°)
OutputlatitudefloatGeographical position - latitude (°)
OutputlongitudefloatGeographical position - longitude (°)
OutputmaneuverAisManeuverIndicatorVessel special maneuver indicator. See maneuver in the Output section for the AisManeuverIndicator enumeration details.
OutputnavigationalStatusAisNavigationStatusNavigational Status in an AIS message. See this FAQ for more information: https://faq.spire.com/how-to-interpret-navigational-status. See AisNavigationStatus in the Output section for the AisNavigationStatus enumeration details.
OutputrotfloatVessel rate of turn (°/min)
OutputspeedfloatVessel speed (knots)
OutputtimestampDateTimeTimestamp of the postiion update (ISO 8601 format).
OutputupdateTimestampDateTimeTimestamp of the update being processed (ISO 8601 format).
OutputstaticDataVesselStaticDataVessel static information.
OutputaisClassAisClassVessel AIS class, A or B. See AisClass in the Output section for the AisClass enumeration details.
OutputdimensionsVesselDimensionsVessel dimensions
OutputaintegerAntenna distance to bow (meters)
OutputbintegerAntenna distance to stern (meters)
OutputcintegerAntenna distance to port (meters)
OutputdintegerAntenna distance to starboard (meters)
OutputlengthintegerVessel length (meters)
OutputwidthintegerVessel width (meters)
OutputshipSubTypeShipSubTypeSubtype of the ship and cargo. See ShipSubType in the Output section for the ShipSubType enumeration details.
OutputpageInfoPageInfoInformation to aid in pagination.
OutputendCursorstringWhen paginating forwards, the cursor continues. This is a cursor pointing to the last element in nodes. Pass this value to after argument to continue pagination on next page.
OutputhasNextPageBooleanThe hasNextPage property indicates whether there are more results to paginate through. Use the endCursor to page through the next results.
OutputtotalCount ResultCountIndicates how many results match the query.
Outputrelation ResultCountRelationEither EQUAL or LOWER_OR_EQUAL
Outputvalue integerInformation about the amount of results in a query. The indicated value might be a lower bound if the total isn't known when there are too many results.

predictedVesselRoute Query Arguments#

In order to get a predictedVesselRoute response, the required parameters are

  • origin
  • destination
  • vessel

All arguments for the vessels query:

predictedVesselRoute(
canals: [WaterwayCanal!] = []
destination: [RouteDestinationInput!]!
origin: RouteOriginInput!
piracy: Boolean = false
speed: Float
vessel: RouteVesselInput!
): VesselRouteResponse

canals#

Specifying this opional parameter will produce a predictedVesselRoute that includes the canals chosen. The canal values are enums, and therefore not quoted in the query.

Available canals: KIEL, PANAMA, SUEZ

Example inclinding both PANAMA and SUEZ:

predictedVesselRoute(
canals: [PANAMA, SUEZ]
. . .

destination#

The required destination is specified by a UNLOCODE

predictedVesselRoute(
destination: USNYC
. . .

origin#

The required origin may be specified by either UNLOCODE or latitude and longitude

Coordinates example:

predictedVesselRoute(
origin{
coordinates: {
latitude: 88
longitude: 123
}
} . . .

UNLOCODE example:

predictedVesselRoute(
origin{
unlocode: USNYC
} . . .

piracy#

Optionally set to flag to allow the route to go through Piracy Zones. If true, predictedVesselRoute will include Piracy Zones If not set, the default is false

predictedVesselRoute(
piracy: true

speed#

Optional average speed in knots which should be used for ETA calculation. If not specified the speed is determined by known speed for the vessel

predictedVesselRoute(
speed: 21.6
. . .

vessel#

Required for obtaining the predictedVesselRoute. Specify mmsi, imo or both. At least one is required

predictedVesselRoute(
vessel: {
imo: 9215696
} . . .

Complete example

predictedVesselRoute(
origin:{
unlocode: USNYC
}
destination:{
unlocode: IRABD
}
vessel: {
imo: 9215696
}
)

predictedVesselRoute Output#

Example query and output specification (note, GraphQL fragments are used below):

query {
predictedVesselRoute(
origin: { unlocode: USNYC }
destination: { unlocode: IRABD }
vessel: { imo: 9215696 }
) {
itinerary {
...RouteDetails
}
journey {
...RouteDetails
}
}
}
fragment PortDetails on Port {
name
unlocode
centerPoint {
latitude
longitude
}
}
fragment RouteDetails on VesselRoute {
distance
duration {
seconds
iso
text
}
eta
seca
destinationPort {
...PortDetails
}
origin {
...PortDetails
}
waypoints {
wkt
geoJson {
coordinates
type
}
}
}

VesselRouteResponse#

The response contains two main objects: itinerary and journey

itinerary#

This object contains two subobjects: PortTurnAround and VesselRoute

PortTurnAround#
type PortTurnaround {
duration: TimeDuration!
port: Port!
}
duration#
type TimeDuration {
iso: String!
seconds: Float!
text: String!
}
port#
type Port {
centerPoint: GeoPoint
name: String!
unlocode: UNLOCODE!
}
centerPoint#
type GeoPoint {
latitude: Float!
longitude: Float!
}

journey#

type VesselRoute {
destinationPort: Port!
distance: Float!
duration: TimeDuration!
eta: DateTime!
origin: RouteOrigin!
seca: Float!
waypoints: Waypoints!
}
waypoints#

Provides waypoints in WKT or GeoJSONLinestring

type Waypoints {
geoJson: GeoJsonLineString
wkt: WKT!
}

matchedPort Arguments#

Obtain port information by supplying search text.

matchedPort(
text: String!
): MatchedPort

matchedPort Output#

  • port is described above
  • matchScore is the confidence value of the match

The match with the highest matchScore is returned

type MatchedPort {
matchScore: Float!
port: Port
}

port Arguments#

Obtain port information given a UNLOCODE. The value for unlocode must be a valid value or an error will be returned

port(
unlocode: UNLOCODE!
): Port

port Output#

type Port {
centerPoint: GeoPoint
name: String!
unlocode: UNLOCODE!
}