[Feature] Add Port Volume Data From EconDB (#6668)

* add port volume data from econdb

* linter

---------

Co-authored-by: Igor Radovanovic <[email protected]>

openbb_platform/core/openbb_core/provider/standard_models/port_volume.py

@@ -0,0 +1,35 @@
+"""Port Volume Standard Model."""
+
+from datetime import date as dateType
+from typing import Optional
+
+from pydantic import Field
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.query_params import QueryParams
+from openbb_core.provider.utils.descriptions import (
+    DATA_DESCRIPTIONS,
+    QUERY_DESCRIPTIONS,
+)
+
+
+class PortVolumeQueryParams(QueryParams):
+    """Port Volume Query."""
+
+    start_date: Optional[dateType] = Field(
+        default=None, description=QUERY_DESCRIPTIONS.get("start_date", "")
+    )
+    end_date: Optional[dateType] = Field(
+        default=None, description=QUERY_DESCRIPTIONS.get("end_date", "")
+    )
+
+
+class PortVolumeData(Data):
+    """Port Volume Data."""
+
+    date: dateType = Field(description=DATA_DESCRIPTIONS.get("date", ""))
+    port_code: Optional[str] = Field(default=None, description="Port code.")
+    port_name: Optional[str] = Field(default=None, description="Port name.")
+    country: Optional[str] = Field(
+        default=None, description="Country where the port is located."
+    )

openbb_platform/extensions/economy/integration/test_economy_api.py

@@ -1156,3 +1156,27 @@ def test_economy_primary_dealer_fails(params, headers):
     result = requests.get(url, headers=headers, timeout=10)
     assert isinstance(result, requests.Response)
     assert result.status_code == 200
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "provider": "econdb",
+                "start_date": None,
+                "end_date": None,
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_economy_port_volume(params, headers):
+    """Test the economy port volume endpoint."""
+    params = {p: v for p, v in params.items() if v}
+
+    query_str = get_querystring(params, [])
+    url = f"http://0.0.0.0:8000/api/v1/economy/port_volume?{query_str}"
+    result = requests.get(url, headers=headers, timeout=10)
+    assert isinstance(result, requests.Response)
+    assert result.status_code == 200

openbb_platform/extensions/economy/integration/test_economy_python.py

@@ -1112,3 +1112,26 @@ def test_economy_primary_dealer_fails(params, obb):
     assert result
     assert isinstance(result, OBBject)
     assert len(result.results) > 0
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "provider": "econdb",
+                "start_date": None,
+                "end_date": None,
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_economy_port_volume(params, obb):
+    """Test the economy port volume endpoint"""
+    params = {p: v for p, v in params.items() if v}
+
+    result = obb.economy.port_volume(**params)
+    assert result
+    assert isinstance(result, OBBject)
+    assert len(result.results) > 0

openbb_platform/extensions/economy/openbb_economy/economy_router.py

@@ -696,3 +696,19 @@ async def primary_dealer_fails(
     re-hypothecation together with the inability or unwillingness to borrow or buy the needed securities."
     """
     return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="PortVolume",
+    examples=[
+        APIEx(parameters={"provider": "econdb"}),
+    ],
+)
+async def port_volume(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get average dwelling times and TEU volumes from the top ports."""
+    return await OBBject.from_query(Query(**locals()))

openbb_platform/openbb/assets/reference.json

@@ -8954,6 +8954,135 @@
             },
             "model": "ExportDestinations"
         },
+        "/economy/port_volume": {
+            "deprecated": {
+                "flag": null,
+                "message": null
+            },
+            "description": "Get average dwelling times and TEU volumes from the top ports.",
+            "examples": "\nExamples\n--------\n\n```python\nfrom openbb import obb\nobb.economy.port_volume(provider='econdb')\n```\n\n",
+            "parameters": {
+                "standard": [
+                    {
+                        "name": "start_date",
+                        "type": "Union[date, str]",
+                        "description": "Start date of the data, in YYYY-MM-DD format.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "end_date",
+                        "type": "Union[date, str]",
+                        "description": "End date of the data, in YYYY-MM-DD format.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    }
+                ],
+                "econdb": []
+            },
+            "returns": {
+                "OBBject": [
+                    {
+                        "name": "results",
+                        "type": "List[PortVolume]",
+                        "description": "Serializable results."
+                    },
+                    {
+                        "name": "provider",
+                        "type": "Optional[Literal['econdb']]",
+                        "description": "Provider name."
+                    },
+                    {
+                        "name": "warnings",
+                        "type": "Optional[List[Warning_]]",
+                        "description": "List of warnings."
+                    },
+                    {
+                        "name": "chart",
+                        "type": "Optional[Chart]",
+                        "description": "Chart object."
+                    },
+                    {
+                        "name": "extra",
+                        "type": "Dict[str, Any]",
+                        "description": "Extra info."
+                    }
+                ]
+            },
+            "data": {
+                "standard": [
+                    {
+                        "name": "date",
+                        "type": "Union[date, str]",
+                        "description": "The date of the data.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    },
+                    {
+                        "name": "port_code",
+                        "type": "str",
+                        "description": "Port code.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "port_name",
+                        "type": "str",
+                        "description": "Port name.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "country",
+                        "type": "str",
+                        "description": "Country where the port is located.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    }
+                ],
+                "econdb": [
+                    {
+                        "name": "export_dwell_time",
+                        "type": "float",
+                        "description": "EconDB model estimate for the average number of days from when a container enters the terminal gates until it is loaded on a vessel. High dwelling times can indicate vessel delays.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "import_dwell_time",
+                        "type": "float",
+                        "description": "EconDB model estimate for the average number of days from when a container is discharged from a vessel until it exits the terminal gates. High dwelling times can indicate trucking or port congestion.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "import_teu",
+                        "type": "int",
+                        "description": "EconDB model estimate for the number of twenty-foot equivalent units (TEUs) of containers imported through the port.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "export_teu",
+                        "type": "int",
+                        "description": "EconDB model estimate for the number of twenty-foot equivalent units (TEUs) of containers exported through the port.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    }
+                ]
+            },
+            "model": "PortVolume"
+        },
         "/economy/primary_dealer_fails": {
             "deprecated": {
                 "flag": null,

openbb_platform/openbb/package/economy.py

@@ -36,6 +36,7 @@ class ROUTER_economy(Container):
     money_measures
     pce
     primary_dealer_fails
+    port_volume
     primary_dealer_positioning
     retail_prices
     risk_premium
@@ -2904,6 +2905,94 @@ def primary_dealer_fails(
             )
         )
 
+    @exception_handler
+    @validate
+    def port_volume(
+        self,
+        start_date: Annotated[
+            Union[datetime.date, None, str],
+            OpenBBField(description="Start date of the data, in YYYY-MM-DD format."),
+        ] = None,
+        end_date: Annotated[
+            Union[datetime.date, None, str],
+            OpenBBField(description="End date of the data, in YYYY-MM-DD format."),
+        ] = None,
+        provider: Annotated[
+            Optional[Literal["econdb"]],
+            OpenBBField(
+                description="The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: econdb."
+            ),
+        ] = None,
+        **kwargs
+    ) -> OBBject:
+        """Get average dwelling times and TEU volumes from the top ports.
+
+        Parameters
+        ----------
+        start_date : Union[date, None, str]
+            Start date of the data, in YYYY-MM-DD format.
+        end_date : Union[date, None, str]
+            End date of the data, in YYYY-MM-DD format.
+        provider : Optional[Literal['econdb']]
+            The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: econdb.
+
+        Returns
+        -------
+        OBBject
+            results : List[PortVolume]
+                Serializable results.
+            provider : Optional[Literal['econdb']]
+                Provider name.
+            warnings : Optional[List[Warning_]]
+                List of warnings.
+            chart : Optional[Chart]
+                Chart object.
+            extra : Dict[str, Any]
+                Extra info.
+
+        PortVolume
+        ----------
+        date : date
+            The date of the data.
+        port_code : Optional[str]
+            Port code.
+        port_name : Optional[str]
+            Port name.
+        country : Optional[str]
+            Country where the port is located.
+        export_dwell_time : Optional[float]
+            EconDB model estimate for the average number of days from when a container enters the terminal gates until it is loaded on a vessel. High dwelling times can indicate vessel delays. (provider: econdb)
+        import_dwell_time : Optional[float]
+            EconDB model estimate for the average number of days from when a container is discharged from a vessel until it exits the terminal gates. High dwelling times can indicate trucking or port congestion. (provider: econdb)
+        import_teu : Optional[int]
+            EconDB model estimate for the number of twenty-foot equivalent units (TEUs) of containers imported through the port. (provider: econdb)
+        export_teu : Optional[int]
+            EconDB model estimate for the number of twenty-foot equivalent units (TEUs) of containers exported through the port. (provider: econdb)
+
+        Examples
+        --------
+        >>> from openbb import obb
+        >>> obb.economy.port_volume(provider='econdb')
+        """  # noqa: E501
+
+        return self._run(
+            "/economy/port_volume",
+            **filter_inputs(
+                provider_choices={
+                    "provider": self._get_provider(
+                        provider,
+                        "economy.port_volume",
+                        ("econdb",),
+                    )
+                },
+                standard_params={
+                    "start_date": start_date,
+                    "end_date": end_date,
+                },
+                extra_params=kwargs,
+            )
+        )
+
     @exception_handler
     @validate
     def primary_dealer_positioning(

openbb_platform/providers/econdb/openbb_econdb/__init__.py

@@ -7,6 +7,7 @@
 from openbb_econdb.models.export_destinations import EconDbExportDestinationsFetcher
 from openbb_econdb.models.gdp_nominal import EconDbGdpNominalFetcher
 from openbb_econdb.models.gdp_real import EconDbGdpRealFetcher
+from openbb_econdb.models.port_volume import EconDbPortVolumeFetcher
 from openbb_econdb.models.yield_curve import EconDbYieldCurveFetcher
 
 econdb_provider = Provider(
@@ -28,6 +29,7 @@
         "ExportDestinations": EconDbExportDestinationsFetcher,
         "GdpNominal": EconDbGdpNominalFetcher,
         "GdpReal": EconDbGdpRealFetcher,
+        "PortVolume": EconDbPortVolumeFetcher,
         "YieldCurve": EconDbYieldCurveFetcher,
     },
     repr_name="EconDB",