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 codeThe 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 PipenvWe 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 RequirementsOnce you have the virtual environment running, install the requirements found in the requirements.txt file.
#
Modify the SettingsNext, 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 - pageInfoThis client requries each query to include a section to request pageInfo
. For example
#
Creating a New QueryTo 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.
#
LoggingThe program creates a log file for debugging purposes named demo_client.log
.
#
Run the ProgramThe 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:
Virtual environment example:
- my_virtual_env as the directory containing the Python virtual environment)
- vessels_v2_graphql as the directory containing this repository
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.