Preparing for Spire Vessels API V2 GraphQL

Advise for Spire clients on preparing for the next release of Vessels API: Vessels API V2 using GraphQL.

Spire Maritime Vessels API is the service that provides the cleaned AIS data and optionally all the premium features not available through the other API services. 

Vessels API V2 is the 2nd iteration of this premium product and has been designed to take the Spire Maritime product set forward, allowing for the easy integration of new product features and for scaling performance as Spire data volumes continue to grow. 

In this article we hope to answer your questions about this product and any plans to migrate to it. However, if your questions are not answered here, then please submit a question through the client support form here.

What are the benefits of Vessels API V2 over Vessels API V1? 

  • New more flexible and easy to use APIs using graphQL
  • Improved and more accurate vessel identification mechanism:
      • Recognising and resolving where possible duplicate vessels reporting using the same MMSI number.
      • Recognising and resolving where possible duplicate vessels reporting using the same IMO number.
      • Maintaining a single vessel history even when changing MMSI number.
  • More data available with:
      • Additional AIS sources - The latest terrestrial partner added March 2021 is only available in the new services. Satellite AIS data from the next generation of Spire satellites will only be included in the new services.
      • Longer historical AIS - 30 days versus 7 days in V1 Messages API.
      • Improved and extended Enhanced Vessel Data (EVD) - Additional EVD partner added and more data fields added to the new service.
  • A single endpoint for all API services: Going forward a single Graph QL endpoint will be used to deliver all core Maritime API services. 
  • Better performance: Quicker and more stable than the V1 API.
  • Faster product development: The new platform creates a scalable architecture that allows for quicker integration of new product features.
  • New Features only available in the new product: Such as Weather Routing and Port Events. 

When will Vessels API V2 GraphQL be available?

Spire expect to release Vessels V2 for Beta testing in July 2021 and for initial release to clients in August 2021. As with all IT development projects, this is subject to the passing of rigorous testing and no unseen technical difficulties, but as of May 2021 initial internal testing has started. 

How long will Vessels API V1 remain available?

Spire will not disable Vessels API V1 until all clients have been migrated. We hope to achieve migration of all users by the end of 2021 and will be providing documentation, sample programs, training and support to help make the transition as easy as possible.

Do licenses/contracts for Vessels API V1 cover Vessels API V2 GraphQL?

Spire customers have contracts granting access to different data sets and different products. Anyone whose contract lists Vessels API will automatically have access to Vessels API V2 GraphQL.

Do we need to change the ETL code to switch to the new API? 

While Spire try to make change as minimally disruptive as possible, the data format of results from the Vessels V2 API will be different from that of the Vessels V1 API. We expect there to be significant similarity but with some subtle differences that are still being worked out. Once the schema of Vessels V2 API results is confirmed details will be published and advice prepared on how to map between the V1 and V2 API results.

But yes ETL or DTS code will need updating to work with the new API.

Is there a change in the API structure?

Vessels V1 is  REST based API.

Vessels V2 is a GraphQL based API.

Both are HTTPS based and return results in JSON format, but the structure of the results will be different, requiring different data mappings (see the answer above about ETL). Also, the method of making requests, known as a query in GraphQL, for data changes a little. The differences will be made clear when migration guides are released.

Could you provide us some detail information? 

Not yet as of May 2021, but we will be able to provide details soon. When we can, we will let our clients know.

What will Spire do to help clients migrate from Vessels V1 to Vessels V2 GraphQL?

Spire Maritime will be releasing detailed documentation about the new API, and sample programs to query the API, demonstrating how to request, receive, and transform data from the new Vessels GraphQL API.  We will also be arranging webinars demonstrating how to use the new API. Finally, as we do currently, we will offer bespoke support to all clients trying to use the new API. This support will be available from the maritime sales engineering team and help should be requested through the client support form here.