`equity.fundamental.dividends`: allow filter by date (#5932)

* allow filter by date

* ruff

* pylint

* fix tests

---------

Co-authored-by: Pratyush Shukla <ps4534@nyu.edu>

5 files changed, 95 insertions, 6 deletions

diff --git a/openbb_platform/core/openbb_core/provider/standard_models/historical_dividends.py b/openbb_platform/core/openbb_core/provider/standard_models/historical_dividends.py
index c45f2065297..b2a3887acd1 100644
--- a/openbb_platform/core/openbb_core/provider/standard_models/historical_dividends.py
+++ b/openbb_platform/core/openbb_core/provider/standard_models/historical_dividends.py
@@ -2,7 +2,7 @@
 
 
 from datetime import date as dateType
-from typing import List, Set, Union
+from typing import List, Optional, Set, Union
 
 from pydantic import Field, field_validator
 
@@ -18,6 +18,12 @@ class HistoricalDividendsQueryParams(QueryParams):
     """Historical Dividends Query."""
 
     symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
+    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", "")
+    )
 
     @field_validator("symbol", mode="before", check_fields=False)
     def upper_symbol(cls, v: Union[str, List[str], Set[str]]):  # pylint: disable=E0213
diff --git a/openbb_platform/extensions/equity/integration/test_equity_api.py b/openbb_platform/extensions/equity/integration/test_equity_api.py
index d71dcea297d..dc30edfc8e5 100644
--- a/openbb_platform/extensions/equity/integration/test_equity_api.py
+++ b/openbb_platform/extensions/equity/integration/test_equity_api.py
@@ -282,14 +282,36 @@ def test_equity_fundamental_historical_splits(params, headers):
 @parametrize(
     "params",
     [
-        ({"symbol": "AAPL", "provider": "fmp"}),
         (
             {
                 "symbol": "AAPL",
+                "start_date": "2021-01-01",
+                "end_date": "2023-06-06",
                 "limit": 100,
                 "provider": "intrinio",
             }
         ),
+        (
+            {
+                "symbol": "AAPL",
+                "start_date": "2021-01-01",
+                "end_date": "2023-06-06",
+                "provider": "fmp",
+            }
+        ),
+        (
+            {
+                "symbol": "AAPL",
+                "limit": 3,
+                "provider": "intrinio",
+            }
+        ),
+        (
+            {
+                "symbol": "AAPL",
+                "provider": "fmp",
+            }
+        ),
     ],
 )
 @pytest.mark.integration
diff --git a/openbb_platform/extensions/equity/integration/test_equity_python.py b/openbb_platform/extensions/equity/integration/test_equity_python.py
index 57d5915acd1..d004d7ef850 100644
--- a/openbb_platform/extensions/equity/integration/test_equity_python.py
+++ b/openbb_platform/extensions/equity/integration/test_equity_python.py
@@ -259,15 +259,36 @@ def test_equity_fundamental_historical_splits(params, obb):
 @parametrize(
     "params",
     [
-        ({"symbol": "AAPL"}),
-        ({"symbol": "AAPL", "provider": "fmp"}),
         (
             {
                 "symbol": "AAPL",
+                "start_date": "2021-01-01",
+                "end_date": "2023-06-06",
                 "limit": 100,
                 "provider": "intrinio",
             }
         ),
+        (
+            {
+                "symbol": "AAPL",
+                "start_date": "2021-01-01",
+                "end_date": "2023-06-06",
+                "provider": "fmp",
+            }
+        ),
+        (
+            {
+                "symbol": "AAPL",
+                "limit": 3,
+                "provider": "intrinio",
+            }
+        ),
+        (
+            {
+                "symbol": "AAPL",
+                "provider": "fmp",
+            }
+        ),
     ],
 )
 @pytest.mark.integration
diff --git a/openbb_platform/openbb/package/equity_fundamental.py b/openbb_platform/openbb/package/equity_fundamental.py
index 5cd6e2e27ee..faadd3a5779 100644
--- a/openbb_platform/openbb/package/equity_fundamental.py
+++ b/openbb_platform/openbb/package/equity_fundamental.py
@@ -941,6 +941,18 @@ class ROUTER_equity_fundamental(Container):
             Union[str, List[str]],
             OpenBBCustomParameter(description="Symbol to get data for."),
         ],
+        start_date: Annotated[
+            Union[datetime.date, None, str],
+            OpenBBCustomParameter(
+                description="Start date of the data, in YYYY-MM-DD format."
+            ),
+        ] = None,
+        end_date: Annotated[
+            Union[datetime.date, None, str],
+            OpenBBCustomParameter(
+                description="End date of the data, in YYYY-MM-DD format."
+            ),
+        ] = None,
         provider: Optional[Literal["fmp", "intrinio"]] = None,
         **kwargs
     ) -> OBBject:
@@ -950,6 +962,10 @@ class ROUTER_equity_fundamental(Container):
         ----------
         symbol : str
             Symbol to get data for.
+        start_date : Optional[datetime.date]
+            Start date of the data, in YYYY-MM-DD format.
+        end_date : Optional[datetime.date]
+            End date of the data, in YYYY-MM-DD format.
         provider : Optional[Literal['fmp', 'intrinio']]
             The provider to use for the query, by default None.
             If None, the provider specified in defaults is selected or 'fmp' if there is
@@ -1008,6 +1024,8 @@ class ROUTER_equity_fundamental(Container):
                 },
                 standard_params={
                     "symbol": ",".join(symbol) if isinstance(symbol, list) else symbol,
+                    "start_date": start_date,
+                    "end_date": end_date,
                 },
                 extra_params=kwargs,
             )
diff --git a/openbb_platform/providers/fmp/openbb_fmp/models/historical_dividends.py b/openbb_platform/providers/fmp/openbb_fmp/models/historical_dividends.py
index 9782e37f06b..bfd7ac6b1a3 100644
--- a/openbb_platform/providers/fmp/openbb_fmp/models/historical_dividends.py
+++ b/openbb_platform/providers/fmp/openbb_fmp/models/historical_dividends.py
@@ -1,8 +1,13 @@
 """FMP Historical Dividends Model."""
 
-from datetime import date as dateType
+from datetime import (
+    date as dateType,
+    datetime,
+)
 from typing import Any, Dict, List, Optional
 
+from dateutil import parser
+from dateutil.relativedelta import relativedelta
 from openbb_core.provider.abstract.fetcher import Fetcher
 from openbb_core.provider.standard_models.historical_dividends import (
     HistoricalDividendsData,
@@ -65,6 +70,14 @@ class FMPHistoricalDividendsFetcher(
     @staticmethod
     def transform_query(params: Dict[str, Any]) -> FMPHistoricalDividendsQueryParams:
         """Transform the query params."""
+        transformed_params = params
+
+        now = datetime.now().date()
+        if params.get("start_date") is None:
+            transformed_params["start_date"] = now - relativedelta(year=1)
+        if params.get("end_date") is None:
+            transformed_params["end_date"] = now
+
         return FMPHistoricalDividendsQueryParams(**params)
 
     @staticmethod
@@ -86,4 +99,13 @@ class FMPHistoricalDividendsFetcher(
         query: FMPHistoricalDividendsQueryParams, data: List[Dict], **kwargs: Any
     ) -> List[FMPHistoricalDividendsData]:
         """Return the transformed data."""
-        return [FMPHistoricalDividendsData.model_validate(d) for d in data]
+        result = []
+        for d in data:
+            if "date" in d:
+                dt = parser.parse(str(d["date"])).date()
+
+                if query.start_date <= dt <= query.end_date:
+                    result.append(FMPHistoricalDividendsData(**d))
+            else:
+                result.append(FMPHistoricalDividendsData(**d))
+        return result