feat: added both afp forecast endpoints

docs/examples/try_me_out/anywhere_freight_pricing_forecast_explanation.ipynb

@@ -0,0 +1,80 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Try out the VortexaSDK"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First let's import our requirements"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vortexasdk import AnywhereFreightPricingForecastExplanation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You'll need to enter your Vortexa API key when prompted."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get monthly forecast explanation for a Handymax MR2 clean route from Rotterdam to Houston\n",
+    "result = AnywhereFreightPricingForecastExplanation().search(\n",
+    "    origin_port=\"68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e\",\n",
+    "    destination_port=\"ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb\",\n",
+    "    vessel_class=\"oil_handymax_mr2\",\n",
+    "    product=\"clean\",\n",
+    "    frequency=\"month\",\n",
+    ")\n",
+    "df = result.to_df()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That's it! You've successfully loaded data using the Vortexa SDK. Check out https://vortechsa.github.io/python-sdk/ for more examples"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

docs/examples/try_me_out/anywhere_freight_pricing_forecast_timeseries.ipynb

@@ -0,0 +1,89 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Try out the VortexaSDK"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First let's import our requirements"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vortexasdk import AnywhereFreightPricingForecastTimeseries\n",
+    "from datetime import datetime"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You'll need to enter your Vortexa API key when prompted."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get weekly forecast pricing for a Handymax MR2 clean route from Rotterdam to Houston\n",
+    "routes = [\n",
+    "    {\n",
+    "        \"origin_port\": \"68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e\",\n",
+    "        \"destination_port\": \"ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb\",\n",
+    "        \"product\": \"clean\",\n",
+    "        \"vessel_class\": \"oil_handymax_mr2\",\n",
+    "    }\n",
+    "]\n",
+    "result = AnywhereFreightPricingForecastTimeseries().search(\n",
+    "    routes=routes,\n",
+    "    time_min=datetime(2026, 6, 1),\n",
+    "    time_max=datetime(2026, 8, 31),\n",
+    "    frequency=\"week\",\n",
+    "    unit=\"usd_per_tonne\",\n",
+    ")\n",
+    "df = result.to_df()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That's it! You've successfully loaded data using the Vortexa SDK. Check out https://vortechsa.github.io/python-sdk/ for more examples"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

mkdocs.yml

@@ -34,6 +34,8 @@ pages:
           Origin: endpoints/anywhere_freight_pricing_top_ports_origin.md
           Destination: endpoints/anywhere_freight_pricing_top_ports_destination.md
         Vessel Classes: endpoints/anywhere_freight_pricing_vessel_classes_details.md
+        Forecast Timeseries: endpoints/anywhere_freight_pricing_forecast_timeseries.md
+        Forecast Explanation: endpoints/anywhere_freight_pricing_forecast_explanation.md
       Vessel Availability:
         Search: endpoints/vessel_availability_search.md
         Time Series: endpoints/vessel_availability_timeseries.md

pydocmd.yml

@@ -109,6 +109,10 @@ generate:
       - vortexasdk.endpoints.anywhere_freight_pricing_top_ports_destination++
   - endpoints/anywhere_freight_pricing_vessel_classes_details.md:
       - vortexasdk.endpoints.anywhere_freight_pricing_vessel_classes_details++
+  - endpoints/anywhere_freight_pricing_forecast_timeseries.md:
+      - vortexasdk.endpoints.anywhere_freight_pricing_forecast_timeseries++
+  - endpoints/anywhere_freight_pricing_forecast_explanation.md:
+      - vortexasdk.endpoints.anywhere_freight_pricing_forecast_explanation++
 pages:
   - Home: index.md << README.md
   - Endpoints:

tests/endpoints/test_anywhere_freight_pricing_forecast_explanation.py

@@ -0,0 +1,72 @@
+from tests.testcases import TestCaseUsingRealAPI
+from vortexasdk import AnywhereFreightPricingForecastExplanation
+
+
+class TestAnywhereFreightPricingForecastExplanation(TestCaseUsingRealAPI):
+    def test_search_returns_data(self):
+        result = AnywhereFreightPricingForecastExplanation().search(
+            origin_port="68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+            destination_port="ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+            vessel_class="oil_handymax_mr2",
+            product="clean",
+            frequency="month",
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) > 0
+        assert "base_date" in result_list[0]
+        assert "explanation" in result_list[0]
+
+    def test_search_to_df(self):
+        result = AnywhereFreightPricingForecastExplanation().search(
+            origin_port="68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+            destination_port="ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+            vessel_class="oil_handymax_mr2",
+            product="clean",
+            frequency="month",
+        )
+
+        df = result.to_df()
+        assert len(df) > 0
+        assert "base_date" in df.columns
+        assert "explanation" in df.columns
+
+    def test_search_with_week_frequency(self):
+        result = AnywhereFreightPricingForecastExplanation().search(
+            origin_port="68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+            destination_port="ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+            vessel_class="oil_handymax_mr2",
+            product="clean",
+            frequency="week",
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) > 0
+        assert "base_date" in result_list[0]
+        assert "explanation" in result_list[0]
+
+    def test_search_with_avoid_zone(self):
+        result = AnywhereFreightPricingForecastExplanation().search(
+            origin_port="68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+            destination_port="ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+            vessel_class="oil_handymax_mr2",
+            product="clean",
+            frequency="month",
+            avoid_zone=["Suez Canal"],
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) > 0
+
+    def test_search_with_include_port_costs(self):
+        result = AnywhereFreightPricingForecastExplanation().search(
+            origin_port="68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+            destination_port="ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+            vessel_class="oil_handymax_mr2",
+            product="clean",
+            frequency="month",
+            include_port_costs=True,
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) > 0

tests/endpoints/test_anywhere_freight_pricing_forecast_timeseries.py

@@ -0,0 +1,84 @@
+from datetime import datetime
+
+from tests.testcases import TestCaseUsingRealAPI
+from vortexasdk import AnywhereFreightPricingForecastTimeseries
+
+
+class TestAnywhereFreightPricingForecastTimeseries(TestCaseUsingRealAPI):
+    def test_search_returns_data(self):
+        routes = [
+            {
+                "origin_port": "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+                "destination_port": "ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+                "product": "clean",
+                "vessel_class": "oil_handymax_mr2",
+            }
+        ]
+
+        result = AnywhereFreightPricingForecastTimeseries().search(
+            routes=routes,
+            time_min=datetime(2026, 5, 26),
+            time_max=datetime(2026, 8, 26),
+            frequency="week",
+            unit="usd_per_tonne",
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) > 0
+        assert "origin_port" in result_list[0]
+        assert "destination_port" in result_list[0]
+        assert "prices" in result_list[0]
+        assert "lumpsums" in result_list[0]
+        assert "suggested_tonnage" in result_list[0]
+
+    def test_search_to_df(self):
+        routes = [
+            {
+                "origin_port": "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+                "destination_port": "ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+                "product": "clean",
+                "vessel_class": "oil_handymax_mr2",
+            }
+        ]
+
+        result = AnywhereFreightPricingForecastTimeseries().search(
+            routes=routes,
+            time_min=datetime(2026, 5, 26),
+            time_max=datetime(2026, 8, 26),
+            frequency="week",
+            unit="usd_per_tonne",
+        )
+
+        df = result.to_df()
+        assert len(df) > 0
+        assert "origin_port" in df.columns
+        assert "destination_port" in df.columns
+        assert "vessel_class" in df.columns
+        assert "suggested_tonnage" in df.columns
+
+    def test_search_multiple_routes(self):
+        routes = [
+            {
+                "origin_port": "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e",
+                "destination_port": "ea4921c8ad4fddb5fe3e7a4f834c1aa5863e43283c73da5f02d93bbc5dba72eb",
+                "vessel_class": "oil_handymax_mr2",
+                "product": "clean",
+            },
+            {
+                "origin_port": "7f314ba0a498c36359b1c88781e94a73e19dcc9bbb030ec6b82f944a73d4da2f",
+                "destination_port": "57a5c821cdc0d9e7187ffc242cd8afd8e86e287b725c1949c65396b575cb5d1e",
+                "vessel_class": "oil_handymax_mr2",
+                "product": "clean",
+            },
+        ]
+
+        result = AnywhereFreightPricingForecastTimeseries().search(
+            routes=routes,
+            time_min=datetime(2026, 5, 26),
+            time_max=datetime(2026, 8, 26),
+            frequency="week",
+            unit="usd_per_tonne",
+        )
+
+        result_list = result.to_list()
+        assert len(result_list) == 2

vortexasdk/__init__.py

@@ -42,13 +42,16 @@
     Refineries,
     AnywhereFreightPricingLatestUpdateTimestamp,
     AnywhereFreightPricingPriceTimeseries,
+    AnywhereFreightPricingForecastTimeseries,
     AnywhereFreightPricingGetPriceDetails,
     AnywhereFreightPricingPostPriceDetails,
     AnywhereFreightPricingTopPortsDestination,
     AnywhereFreightPricingTopPortsOrigin,
     AnywhereFreightPricingVesselClassesDetails,
+    AnywhereFreightPricingForecastExplanation,
     # AFP types
     AfpAvoidZone,
+    AfpExplanationFrequency,
     AfpFrequency,
     AfpProduct,
     AfpRoute,
@@ -104,13 +107,16 @@
     "Refineries",
     "AnywhereFreightPricingLatestUpdateTimestamp",
     "AnywhereFreightPricingPriceTimeseries",
+    "AnywhereFreightPricingForecastTimeseries",
     "AnywhereFreightPricingGetPriceDetails",
     "AnywhereFreightPricingPostPriceDetails",
     "AnywhereFreightPricingTopPortsDestination",
     "AnywhereFreightPricingTopPortsOrigin",
     "AnywhereFreightPricingVesselClassesDetails",
+    "AnywhereFreightPricingForecastExplanation",
     # AFP types
     "AfpAvoidZone",
+    "AfpExplanationFrequency",
     "AfpFrequency",
     "AfpProduct",
     "AfpRoute",