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
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.
Once you have the virtual environment running, install the requirements found in the requirements.txt file.
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.
|The URL to the service|
|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 output log. If blank, no log is produced|
|Name of csv file. If blank, no file is produced|
|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
|Returns all available Vessel, Voyage, and PositionUpdates fields for all vessels globally|
|Returns all available Vessel, Voyage, and PositionUpdates fields for a specific MMSI list|
|Returns all available Vessel, Voyage, and PositionUpdates fields for all vessels in a specified AOI (Indian Ocean)|
This client requries each query to include a section to request
pageInfo. For example
To create a custom query, follow the steps below:
- Create a text file (file with
.txtextension) 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
- Edit the settings.yaml file and add the name of the file you created after
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.
The program creates a log file for debugging purposes named
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.
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
Congratulations! You have successfully executed your first GraphQL query using the Spire Maritime 2.0 API.