Skip to main content

Getting Started

Before accessing this API, you will need to set up an account with the Spire sales team. Contact us to learn more.

Connection#

The following curl command connects to the Vessels endpoint, retrieves data Spire API, and prints the received data to the console. Use the curl command to test your token access.

curl \
--request POST \
--url https://api.spire.com/graphql \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <insert-token>" \
--data '{ "query": "{ vessels(first: 1) { nodes { id staticData { name mmsi imo } lastPositionUpdate { timestamp latitude longitude collectionType } } } } " }'

Queries#

To access the data, you will need to execute a query against the Spire Maritime 2.0 service. Each query is mapped to a specific object type, and each object type has certain fields that can be included or excluded in the query schema to get the desired results. For more information about each object type, please refer to the Output section of the Fundamentals page. To filter the results returned in the query (ie. getting information for a specified list of MMSI or limiting results to a confined area of interest), you will need to specify arguments in parentheses next to the query name.

The queries below are intended to be run in the Playground environment.

Return All Vessels Globally#

Sample of a query that returns all vessels globally. The sample below includes some, but not all available fields:

query {
vessels {
pageInfo {
hasNextPage
endCursor
}
totalCount {
relation
value
}
nodes {
id
updateTimestamp
staticData {
name
imo
mmsi
}
lastPositionUpdate {
latitude
longitude
navigationalStatus
timestamp
updateTimestamp
}
currentVoyage {
destination
draught
eta
timestamp
updateTimestamp
}
}
}
}

Return Partial Fields for All Vessels Globally#

In order to modify what fields are returned in the response, simply modify which fields you request in the request schema. For example, if you would like to only get positional information about the vessels (no static information), you would use this sample query:

query {
vessels {
nodes {
id
lastPositionUpdate {
accuracy
collectionType
course
heading
latitude
longitude
maneuver
navigationalStatus
rot
speed
timestamp
updateTimestamp
}
}
}
}

To further specify which data you would like returned in the response, you would add/delete the fields in the request schema. It is important to note that for GraphQL queries you do not need to make multiple requests to access different resources. For example, if you are only interested in the following fields:

  • id and updateTimestamp fields
  • the vessel name, MMSI, and IMO fields of the staticData type
  • the collectionType, latitude, longitude, and timestamp of the lastPositionUpdate type
  • all pagination related fields from thepageInfo type the query schema would look like this:
query {
vessels {
pageInfo {
hasNextPage
endCursor
}
totalCount {
relation
value
}
nodes {
id
updateTimestamp
staticData {
name
mmsi
imo
}
lastPositionUpdate {
collectionType
latitude
longitude
timestamp
}
}
}
}

Pagination#

There are two arguments in the query used for pagination:

  • first: Int identify how many elements per page you are requesting
  • after: String is a cursor value identifying position to continue pagination.

To query specific number of vessels provide a first argument to the query. The following example returns the first 10 vessels with the recent timestamp:

query {
vessels(first: 10) {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

To enable pagination you need to provide a after argument to the query. The after is equal to the endCursor value from your most recent API request. Thus, to determine the after value, first make your initial query and request the endCursor field.

query {
vessels(first: 10) {
# pagination information
pageInfo {
hasNextPage
endCursor
}
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

This should return results similar to:

{
"data": {
"vessels": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "28a3e8d2-6404-4bd0-9d73-5446c70b78fe@99"
},
"nodes": [ ... ]
}
}
}

Now that you have the endCursor value of your last API request, use this value as the after value in your next request.

query {
vessels(first: 10, after: "28a3e8d2-6404-4bd0-9d73-5446c70b78fe@99") {
pageInfo {
hasNextPage
endCursor
}
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

The hasNextPage value controls the pagination. If it's false than next page is not available and endCursor: null.

Using Arguments to Filter the Results#

As mentioned in the Arguments section of the Fundamentals page, you can pass arguments to fields in order to filter the API results. What you can filter on is determined by the query schema. For example, in the vessels query, the schema looks like this:

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

In the schema above, all the keywords (ie. mmsi, imo, etc.) are the arguments you can pass to the vessels query within the parenthesis. For more information about arguments, please see GraphQL’s documentation here.

Return data for a Specified MMSI List#

Use the MMSI filter in the sample of a query to return data for a given MMSI list. You can see in the sample query that an argument is used to filter on the vessels field, as denoted by the parentheses () next to vessels before the response schema is described in the curly brackets {}.

query {
vessels(mmsi: [412219791, 338153238, 414403750]) {
nodes {
staticData {
aisClass
flag
name
callsign
mmsi
callsign
dimensions {
a
b
c
d
width
length
}
}
lastPositionUpdate {
latitude
longitude
}
currentVoyage {
destination
draught
eta
timestamp
updateTimestamp
}
}
}
}

Return data for a Specified AOI#

Use the areaOfInterest argument to filter the data using an AOI. This could either be a GeoJSON or WKT formatted AOI (there is no need to include both geoJson AND WKT in the same request).

query {
vessels(
areaOfInterest: {
polygon: {
type: "Polygon"
coordinates: [
[
[-122.662353515625, 37.54239958054064]
[-122.13226318359375, 37.54239958054064]
[-122.13226318359375, 37.8813571797486]
[-122.662353515625, 37.8813571797486]
[-122.662353515625, 37.54239958054064]
]
]
}
}
) {
nodes {
staticData {
name
mmsi
}
lastPositionUpdate {
heading
latitude
longitude
}
}
}
}

Example of Using Argument: callsign#

Returns data for the vessel with the callsign of "BOAG9".

query {
vessels(callsign: "BOAG9") {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

Example of Using Argument: flag#

Returns data for the vessel with the flag of "US".

query {
vessels(flag: "US") {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

Example of Using Argument: imo#

Returns data for the vessel with the imo of 9538907.

query {
vessels(imo: [9538907]) {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

Example of Using Argument: lastPositionUpdate#

Returns data for the vessel with the last position updated between timestamps "2021-08-02T00:31:42.780Z" and "2021-08-04T00:31:42.780Z".

query {
vessels(
lastPositionUpdate: {
startTime: "2021-08-02T00:31:42.780Z"
endTime: "2021-08-04T00:31:42.780Z"
}
) {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

Example of Using Argument: name#

Returns data for the vessel with the vessel name of "EAGLE".

query {
vessels(name: "EAGLE") {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}

Example of Using Argument: shipType#

Returns data for all General Cargo and Container vessels.

query {
vessels(shipType: [GENERAL_CARGO, CONTAINER]) {
nodes {
staticData {
name
mmsi
imo
}
lastPositionUpdate {
timestamp
latitude
longitude
collectionType
}
}
}
}