From 5943c3ed89a78babc868ee2357103ff03afa6e10 Mon Sep 17 00:00:00 2001 From: kdalkas Date: Mon, 11 May 2026 15:49:07 +0100 Subject: [PATCH 1/2] docs: add availability note to vessel_risk_level docstrings --- .../Case Study of Voyages data.ipynb | 9 ++++++--- .../Fleet distribution per location.ipynb | 11 +++++++---- vortexasdk/endpoints/vessel_availability_breakdown.py | 4 ++++ vortexasdk/endpoints/vessel_availability_search.py | 4 ++++ .../endpoints/vessel_availability_timeseries.py | 4 ++++ vortexasdk/endpoints/voyages_congestion_breakdown.py | 4 ++++ vortexasdk/endpoints/voyages_geography_breakdown.py | 4 ++++ vortexasdk/endpoints/voyages_product_breakdown.py | 4 ++++ vortexasdk/endpoints/voyages_routes_breakdown.py | 4 ++++ vortexasdk/endpoints/voyages_search_enriched.py | 4 ++++ vortexasdk/endpoints/voyages_timeseries.py | 4 ++++ vortexasdk/endpoints/voyages_timeseries_v2.py | 4 ++++ vortexasdk/endpoints/voyages_top_hits.py | 4 ++++ .../endpoints/voyages_vessel_class_breakdown.py | 4 ++++ 14 files changed, 61 insertions(+), 7 deletions(-) diff --git a/docs/examples/academy_use_cases/Freight & Voyages/Case Study of Voyages data.ipynb b/docs/examples/academy_use_cases/Freight & Voyages/Case Study of Voyages data.ipynb index ea3f99f3..5e5983e4 100644 --- a/docs/examples/academy_use_cases/Freight & Voyages/Case Study of Voyages data.ipynb +++ b/docs/examples/academy_use_cases/Freight & Voyages/Case Study of Voyages data.ipynb @@ -1440,7 +1440,10 @@ "metadata": {}, "source": [ "# Example 1: Fleet distribution per location\n", - "Track changes in tanker numbers in a custom set of Vortexa locations. In this example we monitor the supply of MR2 tankers in each basin (Atlantic and Pacific). This can indicate where supply side pressure might come into play for freight rates in various regions, as well as highlight changes in tanker migration patterns." + "Track changes in tanker numbers in a custom set of Vortexa locations. In this example we monitor the supply of MR2 tankers in each basin (Atlantic and Pacific). This can indicate where supply side pressure might come into play for freight rates in various regions, as well as highlight changes in tanker migration patterns.", + "\n", + "\n", + "**Note:** *The `risk_rating` and `risk_rating_excl` parameters (which map to `vessel_risk_level` and `vessel_risk_level_excluded` in the API) may not be available for all accounts. If not available, the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data.*" ] }, { @@ -3203,7 +3206,7 @@ " \n", " \n", "\n", - "

164 rows × 3 columns

\n", + "

164 rows \u00d7 3 columns

\n", "" ], "text/plain": [ @@ -3404,4 +3407,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/docs/examples/academy_use_cases/Freight & Voyages/Fleet distribution per location.ipynb b/docs/examples/academy_use_cases/Freight & Voyages/Fleet distribution per location.ipynb index 74d87de6..6e24369d 100644 --- a/docs/examples/academy_use_cases/Freight & Voyages/Fleet distribution per location.ipynb +++ b/docs/examples/academy_use_cases/Freight & Voyages/Fleet distribution per location.ipynb @@ -1449,7 +1449,10 @@ "metadata": {}, "source": [ "# Example 1: Fleet distribution per location\n", - "Track changes in tanker numbers in a custom set of Vortexa locations. In this example we monitor the supply of MR2 tankers in each basin (Atlantic and Pacific). This can indicate where supply side pressure might come into play for freight rates in various regions, as well as highlight changes in tanker migration patterns." + "Track changes in tanker numbers in a custom set of Vortexa locations. In this example we monitor the supply of MR2 tankers in each basin (Atlantic and Pacific). This can indicate where supply side pressure might come into play for freight rates in various regions, as well as highlight changes in tanker migration patterns.", + "\n", + "\n", + "**Note:** *The `risk_rating` and `risk_rating_excl` parameters (which map to `vessel_risk_level` and `vessel_risk_level_excluded` in the API) may not be available for all accounts. If not available, the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data.*" ] }, { @@ -1467,7 +1470,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "2024-09-17 15:52:52,899 vortexasdk.client — WARNING — You are using vortexasdk version 0.73.0, however version 0.73.1 is available.\n", + "2024-09-17 15:52:52,899 vortexasdk.client \u2014 WARNING \u2014 You are using vortexasdk version 0.73.0, however version 0.73.1 is available.\n", "You should consider upgrading via the 'pip install vortexasdk --upgrade' command.\n", "Downloading vessel_count for period: 2018-01-01 00:00:00 to 2021-12-31 23:59:59\n", "Downloading vessel_count for period: 2022-01-01 00:00:00 to 2024-09-17 15:53:38.241636\n", @@ -15340,7 +15343,7 @@ " \n", " \n", "\n", - "

196 rows × 3 columns

\n", + "

196 rows \u00d7 3 columns

\n", "" ], "text/plain": [ @@ -42604,4 +42607,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/vortexasdk/endpoints/vessel_availability_breakdown.py b/vortexasdk/endpoints/vessel_availability_breakdown.py index 7f62afc5..40bb741a 100644 --- a/vortexasdk/endpoints/vessel_availability_breakdown.py +++ b/vortexasdk/endpoints/vessel_availability_breakdown.py @@ -118,6 +118,8 @@ def search( filter_vessel_tags: A tag ID, or list of tag IDs to filter on. filter_vessel_risk_level: A risk level ID, or list of risk level IDs to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. filter_recent_visits: Filter availability by each vessel's recent visits @@ -142,6 +144,8 @@ def search( exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. # Returns `TimeSeriesResult` diff --git a/vortexasdk/endpoints/vessel_availability_search.py b/vortexasdk/endpoints/vessel_availability_search.py index d5a85e35..d1767847 100644 --- a/vortexasdk/endpoints/vessel_availability_search.py +++ b/vortexasdk/endpoints/vessel_availability_search.py @@ -131,6 +131,8 @@ def search( filter_vessel_tags: A tag ID, or list of tag IDs to filter on. filter_vessel_risk_level: A risk level ID, or list of risk level IDs to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. filter_recent_visits: Filter availability by each vessel's recent visits @@ -155,6 +157,8 @@ def search( exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. # Returns `VesselAvailabilityResult` diff --git a/vortexasdk/endpoints/vessel_availability_timeseries.py b/vortexasdk/endpoints/vessel_availability_timeseries.py index 877eb970..f1228f5d 100644 --- a/vortexasdk/endpoints/vessel_availability_timeseries.py +++ b/vortexasdk/endpoints/vessel_availability_timeseries.py @@ -128,6 +128,8 @@ def search( filter_vessel_tags: A tag ID, or list of tag IDs to filter on. filter_vessel_risk_level: A risk level ID, or list of risk level IDs to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. exclude_products: A product ID, or list of product IDs to exclude. @@ -150,6 +152,8 @@ def search( exclude_vessel_tags: A tag ID, or list of tag IDs to exclude. exclude_vessel_risk_level: A risk level ID, or list of risk level IDs to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. # Returns `TimeSeriesResult` diff --git a/vortexasdk/endpoints/voyages_congestion_breakdown.py b/vortexasdk/endpoints/voyages_congestion_breakdown.py index c05b4823..9d3fb1d3 100644 --- a/vortexasdk/endpoints/voyages_congestion_breakdown.py +++ b/vortexasdk/endpoints/voyages_congestion_breakdown.py @@ -209,8 +209,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_geography_breakdown.py b/vortexasdk/endpoints/voyages_geography_breakdown.py index c07faee4..99e56aa0 100644 --- a/vortexasdk/endpoints/voyages_geography_breakdown.py +++ b/vortexasdk/endpoints/voyages_geography_breakdown.py @@ -254,8 +254,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_product_breakdown.py b/vortexasdk/endpoints/voyages_product_breakdown.py index 52d79735..3bda6215 100644 --- a/vortexasdk/endpoints/voyages_product_breakdown.py +++ b/vortexasdk/endpoints/voyages_product_breakdown.py @@ -254,8 +254,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_routes_breakdown.py b/vortexasdk/endpoints/voyages_routes_breakdown.py index c0185b23..4b916012 100644 --- a/vortexasdk/endpoints/voyages_routes_breakdown.py +++ b/vortexasdk/endpoints/voyages_routes_breakdown.py @@ -253,8 +253,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_search_enriched.py b/vortexasdk/endpoints/voyages_search_enriched.py index f164652a..2ebbb5af 100644 --- a/vortexasdk/endpoints/voyages_search_enriched.py +++ b/vortexasdk/endpoints/voyages_search_enriched.py @@ -220,8 +220,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of `disabled`, `inc`, `exc`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_timeseries.py b/vortexasdk/endpoints/voyages_timeseries.py index 8cc9e599..3b0f4f6e 100644 --- a/vortexasdk/endpoints/voyages_timeseries.py +++ b/vortexasdk/endpoints/voyages_timeseries.py @@ -217,8 +217,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_timeseries_v2.py b/vortexasdk/endpoints/voyages_timeseries_v2.py index 65ba86e0..afc277f7 100644 --- a/vortexasdk/endpoints/voyages_timeseries_v2.py +++ b/vortexasdk/endpoints/voyages_timeseries_v2.py @@ -248,8 +248,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_top_hits.py b/vortexasdk/endpoints/voyages_top_hits.py index 146eddad..8d568414 100644 --- a/vortexasdk/endpoints/voyages_top_hits.py +++ b/vortexasdk/endpoints/voyages_top_hits.py @@ -216,8 +216,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. diff --git a/vortexasdk/endpoints/voyages_vessel_class_breakdown.py b/vortexasdk/endpoints/voyages_vessel_class_breakdown.py index 4be1dc16..ee9efb59 100644 --- a/vortexasdk/endpoints/voyages_vessel_class_breakdown.py +++ b/vortexasdk/endpoints/voyages_vessel_class_breakdown.py @@ -251,8 +251,12 @@ def search( vessel_tags_excluded: A time bound vessel tag, or list of time bound vessel tags to exclude. vessel_risk_level: A vessel risk level, or list of vessel risk levels to filter on. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored, results will not be filtered by risk level, and vessel_risk_level will not appear in response data. vessel_risk_level_excluded: A vessel risk level, or list of vessel risk levels to exclude. + Note: This filter may not be available for all accounts. If not available, + the filter will be ignored and vessel_risk_level will not appear in response data. has_ship_to_ship: Filter data where at least one STS transfer occurs, or none. - one of: `'disabled'`, `'inc'`, `'exc'`. Passing disabled means the filter is not active. From 5d2bc711fb2869a6da787abc9e1d726e1a7c24b0 Mon Sep 17 00:00:00 2001 From: kdalkas Date: Tue, 12 May 2026 10:05:53 +0100 Subject: [PATCH 2/2] feat: bump version --- vortexasdk/version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vortexasdk/version.py b/vortexasdk/version.py index 00188284..9b719b6e 100644 --- a/vortexasdk/version.py +++ b/vortexasdk/version.py @@ -1 +1 @@ -__version__ = "1.0.24" +__version__ = "1.0.25"