Connecting to the Spire Maritime API with Python

In this tutorial, we will go through the steps necessary to connect to the Spire Maritime 2.0 API using a sample Python client. With this sample program, you may execute the following queries:

Return data for all vessels globally
Return data for a specific MMSI list
Return data for all vessels in a specified AOI

Source code#

The tutorial code is for demonstation purposes and should not be used in production. The code is not included in a customer support contract unless explicately documented elsewhere.

You can find the source code of the following tutorial here.

Using Pipenv#

We recommend using a virtual environment, such as pipenv, when completing this tutorial. To start a Pipenv virtual environment, some have found this tutorial to be useful.

Install the Requirements#

Once you have the virtual environment running, install the requirements found in the requirements.txt file.

pip3 install -r requirements.txt

Modify the Settings#

Next, edit the settings.yaml file to reflect your environment. Note: all files are assumed to be in the same directory as the program. Below are descriptions of each variable in the setting file.

Setting	Info
`endpoint`	The URL to the service
`token`	Authentication token
`name_of_gql_query_file`	Name of file containing query to execute. Currently there are three: sample_1.txt, sample_2.txt, and sample_3.txt. See descriptions below.
`name_of_raw_ouput_file`	Name of raw output log. If blank, no log is produced
`name_of_csv_file`	Name of csv file. If blank, no file is produced
`pages_to_process`	Max number of pages to process. A helpful setting for debugging. If set to 0, all pages are processed

There are three sample queries provided in the program that are set in the name_of_gql_query_file variable:

Setting	Info
`sample_1.txt`	Returns all available Vessel, Voyage, and PositionUpdates fields for all vessels globally
`sample_2.txt`	Returns all available Vessel, Voyage, and PositionUpdates fields for a specific MMSI list
`sample_3.txt`	Returns all available Vessel, Voyage, and PositionUpdates fields for all vessels in a specified AOI (Indian Ocean)

Important Note - pageInfo#

This client requries each query to include a section to request pageInfo. For example

query{ 
  pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      id
      updateTimestamp
      staticData {
        imo . . .
   }

Creating a New Query#

To create a custom query, follow the steps below:

Create a text file (file with .txt extension) in the same folder that you saved the sample python client files in your Pipenv virtual environment.
Write a query using the samples as a guide. Information about writing queries can also be found in the Getting Started Guide. Please review the the important note regarding pageInfo above.
Edit the settings.yaml file and add the name of the file you created after name_of_gql_query_file. Example: name_of_gql_query_file: 'my-new_query.txt'

When writing a custom query file, it is important that you do not place any comments or text that does not represent a query in the newly created file.

Logging#

The program creates a log file for debugging purposes named demo_client.log.

Run the Program#

The run.py program will read the settings.yaml file and execute a query based on the fields listed in the specified file in name_of_gql_query_file variable. To run the program, execute the following code in the virtual environment.

Pipenv example:

pipenv run python3 run.py

Virtual environment example:

my_virtual_env as the directory containing the Python virtual environment)
vessels_v2_graphql as the directory containing this repository

source my_virtual_env/bin/activate  [ENTER]
cd vessels_v2_graphql [ENTER]
python3 run.py

If you specified the desired name of the CSV file in the name_of_csv_file variable and/or the name of the output log in the name_of_raw_output_file variable, these files can be accessed in your directory once the program completes. All log information for debugging purposes can be found in the file demo_client.log.

Congratulations! You have successfully executed your first GraphQL query using the Spire Maritime 2.0 API.