fmp key metrics (#6428)

Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>

3 files changed, 195 insertions, 144 deletions

diff --git a/openbb_platform/openbb/assets/reference.json b/openbb_platform/openbb/assets/reference.json
index 5449acc33c9..0c7ed54c228 100644
--- a/openbb_platform/openbb/assets/reference.json
+++ b/openbb_platform/openbb/assets/reference.json
@@ -15754,15 +15754,15 @@
                 ],
                 "fmp": [
                     {
-                        "name": "date",
+                        "name": "period_ending",
                         "type": "date",
-                        "description": "The date of the data.",
+                        "description": "Period ending date.",
                         "default": "",
                         "optional": false,
                         "choices": null
                     },
                     {
-                        "name": "period",
+                        "name": "fiscal_period",
                         "type": "str",
                         "description": "Period of the data.",
                         "default": "",
@@ -15772,7 +15772,7 @@
                     {
                         "name": "calendar_year",
                         "type": "int",
-                        "description": "Calendar year.",
+                        "description": "Calendar year for the fiscal period.",
                         "default": null,
                         "optional": true,
                         "choices": null
@@ -15786,6 +15786,14 @@
                         "choices": null
                     },
                     {
+                        "name": "capex_per_share",
+                        "type": "float",
+                        "description": "Capital expenditures per share",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
                         "name": "net_income_per_share",
                         "type": "float",
                         "description": "Net income per share",
@@ -15850,15 +15858,7 @@
                         "choices": null
                     },
                     {
-                        "name": "enterprise_value",
-                        "type": "float",
-                        "description": "Enterprise value",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
-                        "name": "price_to_sales_ratio",
+                        "name": "price_to_sales",
                         "type": "float",
                         "description": "Price-to-sales ratio",
                         "default": null,
@@ -15866,7 +15866,7 @@
                         "choices": null
                     },
                     {
-                        "name": "pocf_ratio",
+                        "name": "price_to_operating_cash_flow",
                         "type": "float",
                         "description": "Price-to-operating cash flow ratio",
                         "default": null,
@@ -15874,7 +15874,7 @@
                         "choices": null
                     },
                     {
-                        "name": "pfcf_ratio",
+                        "name": "price_to_free_cash_flow",
                         "type": "float",
                         "description": "Price-to-free cash flow ratio",
                         "default": null,
@@ -15882,7 +15882,7 @@
                         "choices": null
                     },
                     {
-                        "name": "pb_ratio",
+                        "name": "price_to_book",
                         "type": "float",
                         "description": "Price-to-book ratio",
                         "default": null,
@@ -15890,7 +15890,7 @@
                         "choices": null
                     },
                     {
-                        "name": "ptb_ratio",
+                        "name": "price_to_tangible_book",
                         "type": "float",
                         "description": "Price-to-tangible book ratio",
                         "default": null,
@@ -15906,7 +15906,7 @@
                         "choices": null
                     },
                     {
-                        "name": "enterprise_value_over_ebitda",
+                        "name": "ev_to_ebitda",
                         "type": "float",
                         "description": "Enterprise value-to-EBITDA ratio",
                         "default": null,
@@ -15946,6 +15946,14 @@
                         "choices": null
                     },
                     {
+                        "name": "debt_to_market_cap",
+                        "type": "float",
+                        "description": "Debt-to-market capitalization ratio",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
                         "name": "debt_to_equity",
                         "type": "float",
                         "description": "Debt-to-equity ratio",
@@ -15994,14 +16002,6 @@
                         "choices": null
                     },
                     {
-                        "name": "dividend_yield",
-                        "type": "float",
-                        "description": "Dividend yield, as a normalized percent.",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
                         "name": "payout_ratio",
                         "type": "float",
                         "description": "Payout ratio",
@@ -16066,38 +16066,6 @@
                         "choices": null
                     },
                     {
-                        "name": "graham_number",
-                        "type": "float",
-                        "description": "Graham number",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
-                        "name": "roic",
-                        "type": "float",
-                        "description": "Return on invested capital",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
-                        "name": "return_on_tangible_assets",
-                        "type": "float",
-                        "description": "Return on tangible assets",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
-                        "name": "graham_net_net",
-                        "type": "float",
-                        "description": "Graham net-net working capital",
-                        "default": null,
-                        "optional": true,
-                        "choices": null
-                    },
-                    {
                         "name": "working_capital",
                         "type": "float",
                         "description": "Working capital",
@@ -16122,6 +16090,14 @@
                         "choices": null
                     },
                     {
+                        "name": "enterprise_value",
+                        "type": "float",
+                        "description": "Enterprise value",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
                         "name": "invested_capital",
                         "type": "float",
                         "description": "Invested capital",
@@ -16202,7 +16178,7 @@
                         "choices": null
                     },
                     {
-                        "name": "roe",
+                        "name": "return_on_equity",
                         "type": "float",
                         "description": "Return on equity",
                         "default": null,
@@ -16210,9 +16186,41 @@
                         "choices": null
                     },
                     {
-                        "name": "capex_per_share",
+                        "name": "return_on_invested_capital",
                         "type": "float",
-                        "description": "Capital expenditures per share",
+                        "description": "Return on invested capital",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "return_on_tangible_assets",
+                        "type": "float",
+                        "description": "Return on tangible assets",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "dividend_yield",
+                        "type": "float",
+                        "description": "Dividend yield, as a normalized percent.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "graham_number",
+                        "type": "float",
+                        "description": "Graham number",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "graham_net_net",
+                        "type": "float",
+                        "description": "Graham net-net working capital",
                         "default": null,
                         "optional": true,
                         "choices": null
diff --git a/openbb_platform/openbb/package/equity_fundamental.py b/openbb_platform/openbb/package/equity_fundamental.py
index cc734d0f02a..90077853ac8 100644
--- a/openbb_platform/openbb/package/equity_fundamental.py
+++ b/openbb_platform/openbb/package/equity_fundamental.py
@@ -2420,14 +2420,16 @@ class ROUTER_equity_fundamental(Container):
             Market capitalization
         pe_ratio : Optional[float]
             Price-to-earnings ratio (P/E ratio)
-        date : Optional[date]
-            The date of the data. (provider: fmp)
-        period : Optional[str]
+        period_ending : Optional[date]
+            Period ending date. (provider: fmp)
+        fiscal_period : Optional[str]
             Period of the data. (provider: fmp)
         calendar_year : Optional[int]
-            Calendar year. (provider: fmp)
+            Calendar year for the fiscal period. (provider: fmp)
         revenue_per_share : Optional[float]
             Revenue per share (provider: fmp, yfinance)
+        capex_per_share : Optional[float]
+            Capital expenditures per share (provider: fmp)
         net_income_per_share : Optional[float]
             Net income per share (provider: fmp)
         operating_cash_flow_per_share : Optional[float]
@@ -2444,21 +2446,19 @@ class ROUTER_equity_fundamental(Container):
             Shareholders equity per share (provider: fmp)
         interest_debt_per_share : Optional[float]
             Interest debt per share (provider: fmp)
-        enterprise_value : Optional[int]
-            Enterprise value (provider: fmp, intrinio, yfinance)
-        price_to_sales_ratio : Optional[float]
+        price_to_sales : Optional[float]
             Price-to-sales ratio (provider: fmp)
-        pocf_ratio : Optional[float]
+        price_to_operating_cash_flow : Optional[float]
             Price-to-operating cash flow ratio (provider: fmp)
-        pfcf_ratio : Optional[float]
+        price_to_free_cash_flow : Optional[float]
             Price-to-free cash flow ratio (provider: fmp)
-        pb_ratio : Optional[float]
-            Price-to-book ratio (provider: fmp)
-        ptb_ratio : Optional[float]
-            Price-to-tangible book ratio (provider: fmp)
+        price_to_book : Optional[float]
+            Price-to-book ratio (provider: fmp, intrinio, yfinance)
+        price_to_tangible_book : Optional[float]
+            Price-to-tangible book ratio (provider: fmp, intrinio)
         ev_to_sales : Optional[float]
             Enterprise value-to-sales ratio (provider: fmp)
-        enterprise_value_over_ebitda : Optional[float]
+        ev_to_ebitda : Optional[float]
             Enterprise value-to-EBITDA ratio (provider: fmp)
         ev_to_operating_cash_flow : Optional[float]
             Enterprise value-to-operating cash flow ratio (provider: fmp)
@@ -2469,6 +2469,8 @@ class ROUTER_equity_fundamental(Container):
             Earnings yield, as a normalized percent. (provider: intrinio)
         free_cash_flow_yield : Optional[float]
             Free cash flow yield (provider: fmp)
+        debt_to_market_cap : Optional[float]
+            Debt-to-market capitalization ratio (provider: fmp)
         debt_to_equity : Optional[float]
             Debt-to-equity ratio (provider: fmp, yfinance)
         debt_to_assets : Optional[float]
@@ -2481,8 +2483,6 @@ class ROUTER_equity_fundamental(Container):
             Interest coverage (provider: fmp)
         income_quality : Optional[float]
             Income quality (provider: fmp)
-        dividend_yield : Optional[float]
-            Dividend yield, as a normalized percent. (provider: fmp, intrinio, yfinance)
         payout_ratio : Optional[float]
             Payout ratio (provider: fmp, yfinance)
         sales_general_and_administrative_to_revenue : Optional[float]
@@ -2499,20 +2499,14 @@ class ROUTER_equity_fundamental(Container):
             Capital expenditures-to-depreciation ratio (provider: fmp)
         stock_based_compensation_to_revenue : Optional[float]
             Stock-based compensation-to-revenue ratio (provider: fmp)
-        graham_number : Optional[float]
-            Graham number (provider: fmp)
-        roic : Optional[float]
-            Return on invested capital (provider: fmp)
-        return_on_tangible_assets : Optional[float]
-            Return on tangible assets (provider: fmp)
-        graham_net_net : Optional[float]
-            Graham net-net working capital (provider: fmp)
         working_capital : Optional[float]
             Working capital (provider: fmp)
         tangible_asset_value : Optional[float]
             Tangible asset value (provider: fmp)
         net_current_asset_value : Optional[float]
             Net current asset value (provider: fmp)
+        enterprise_value : Optional[int]
+            Enterprise value (provider: fmp, intrinio, yfinance)
         invested_capital : Optional[float]
             Invested capital (provider: fmp)
         average_receivables : Optional[float]
@@ -2533,14 +2527,21 @@ class ROUTER_equity_fundamental(Container):
             Payables turnover (provider: fmp)
         inventory_turnover : Optional[float]
             Inventory turnover (provider: fmp)
-        roe : Optional[float]
-            Return on equity (provider: fmp)
-        capex_per_share : Optional[float]
-            Capital expenditures per share (provider: fmp)
-        price_to_book : Optional[float]
-            Price to book ratio. (provider: intrinio, yfinance)
-        price_to_tangible_book : Optional[float]
-            Price to tangible book ratio. (provider: intrinio)
+        return_on_equity : Optional[float]
+            Return on equity (provider: fmp);
+            Return on equity, as a normalized percent. (provider: intrinio);
+            Return on equity, as a normalized percent. (provider: yfinance)
+        return_on_invested_capital : Optional[float]
+            Return on invested capital (provider: fmp);
+            Return on invested capital, as a normalized percent. (provider: intrinio)
+        return_on_tangible_assets : Optional[float]
+            Return on tangible assets (provider: fmp)
+        dividend_yield : Optional[float]
+            Dividend yield, as a normalized percent. (provider: fmp, intrinio, yfinance)
+        graham_number : Optional[float]
+            Graham number (provider: fmp)
+        graham_net_net : Optional[float]
+            Graham net-net working capital (provider: fmp)
         price_to_revenue : Optional[float]
             Price to revenue ratio. (provider: intrinio)
         quick_ratio : Optional[float]
@@ -2569,10 +2570,6 @@ class ROUTER_equity_fundamental(Container):
             Invested capital growth, as a normalized percent. (provider: intrinio)
         return_on_assets : Optional[float]
             Return on assets, as a normalized percent. (provider: intrinio, yfinance)
-        return_on_equity : Optional[float]
-            Return on equity, as a normalized percent. (provider: intrinio, yfinance)
-        return_on_invested_capital : Optional[float]
-            Return on invested capital, as a normalized percent. (provider: intrinio)
         ebitda : Optional[int]
             Earnings before interest, taxes, depreciation, and amortization. (provider: intrinio)
         ebit : Optional[int]
diff --git a/openbb_platform/providers/fmp/openbb_fmp/models/key_metrics.py b/openbb_platform/providers/fmp/openbb_fmp/models/key_metrics.py
index c47a214a786..5b2ef4f2cb1 100644
--- a/openbb_platform/providers/fmp/openbb_fmp/models/key_metrics.py
+++ b/openbb_platform/providers/fmp/openbb_fmp/models/key_metrics.py
@@ -1,5 +1,7 @@
 """FMP Key Metrics Model."""
 
+# pylint: disable=unused-argument
+
 import asyncio
 from datetime import (
     date as dateType,
@@ -14,7 +16,6 @@ from openbb_core.provider.standard_models.key_metrics import (
     KeyMetricsData,
     KeyMetricsQueryParams,
 )
-from openbb_core.provider.utils.descriptions import DATA_DESCRIPTIONS
 from openbb_core.provider.utils.errors import EmptyDataError
 from openbb_core.provider.utils.helpers import amake_request
 from openbb_fmp.utils.helpers import response_callback
@@ -37,14 +38,24 @@ class FMPKeyMetricsQueryParams(KeyMetricsQueryParams):
 class FMPKeyMetricsData(KeyMetricsData):
     """FMP Key Metrics Data."""
 
-    date: dateType = Field(description=DATA_DESCRIPTIONS.get("date", ""))
-    period: str = Field(description="Period of the data.")
+    __alias_dict__ = {
+        "dividend_yield": "dividend_yiel",
+        "market_cap": "marketCap",
+        "research_and_development_to_revenue": "researchAndDevelopementToRevenue",
+        "fiscal_period": "period",
+        "period_ending": "date",
+    }
+    period_ending: dateType = Field(description="Period ending date.")
+    fiscal_period: str = Field(description="Period of the data.")
     calendar_year: Optional[ForceInt] = Field(
-        default=None, description="Calendar year."
+        default=None, description="Calendar year for the fiscal period."
     )
     revenue_per_share: Optional[float] = Field(
         default=None, description="Revenue per share"
     )
+    capex_per_share: Optional[float] = Field(
+        default=None, description="Capital expenditures per share"
+    )
     net_income_per_share: Optional[float] = Field(
         default=None, description="Net income per share"
     )
@@ -67,28 +78,37 @@ class FMPKeyMetricsData(KeyMetricsData):
     interest_debt_per_share: Optional[float] = Field(
         default=None, description="Interest debt per share"
     )
-    enterprise_value: Optional[float] = Field(
-        default=None, description="Enterprise value"
-    )
-    price_to_sales_ratio: Optional[float] = Field(
-        default=None, description="Price-to-sales ratio"
+    price_to_sales: Optional[float] = Field(
+        default=None,
+        description="Price-to-sales ratio",
+        alias="priceToSalesRatio",
     )
-    pocf_ratio: Optional[float] = Field(
+    price_to_operating_cash_flow: Optional[float] = Field(
         default=None,
         description="Price-to-operating cash flow ratio",
         alias="pocfratio",
     )
-    pfcf_ratio: Optional[float] = Field(
-        default=None, description="Price-to-free cash flow ratio"
+    price_to_free_cash_flow: Optional[float] = Field(
+        default=None,
+        description="Price-to-free cash flow ratio",
+        alias="pfcfRatio",
+    )
+    price_to_book: Optional[float] = Field(
+        default=None,
+        description="Price-to-book ratio",
+        alias="pbRatio",
     )
-    pb_ratio: Optional[float] = Field(default=None, description="Price-to-book ratio")
-    ptb_ratio: Optional[float] = Field(
-        default=None, description="Price-to-tangible book ratio"
+    price_to_tangible_book: Optional[float] = Field(
+        default=None,
+        description="Price-to-tangible book ratio",
+        alias="ptbRatio",
     )
     ev_to_sales: Optional[float] = Field(
-        default=None, description="Enterprise value-to-sales ratio"
+        default=None,
+        description="Enterprise value-to-sales ratio",
+        alias="evToSales",
     )
-    enterprise_value_over_ebitda: Optional[float] = Field(
+    ev_to_ebitda: Optional[float] = Field(
         default=None,
         description="Enterprise value-to-EBITDA ratio",
         alias="enterpriseValueOverEBITDA",
@@ -99,9 +119,18 @@ class FMPKeyMetricsData(KeyMetricsData):
     ev_to_free_cash_flow: Optional[float] = Field(
         default=None, description="Enterprise value-to-free cash flow ratio"
     )
-    earnings_yield: Optional[float] = Field(default=None, description="Earnings yield")
+    earnings_yield: Optional[float] = Field(
+        default=None,
+        description="Earnings yield",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+    )
     free_cash_flow_yield: Optional[float] = Field(
-        default=None, description="Free cash flow yield"
+        default=None,
+        description="Free cash flow yield",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+    )
+    debt_to_market_cap: Optional[float] = Field(
+        default=None, description="Debt-to-market capitalization ratio"
     )
     debt_to_equity: Optional[float] = Field(
         default=None, description="Debt-to-equity ratio"
@@ -119,11 +148,6 @@ class FMPKeyMetricsData(KeyMetricsData):
         default=None, description="Interest coverage"
     )
     income_quality: Optional[float] = Field(default=None, description="Income quality")
-    dividend_yield: Optional[float] = Field(
-        default=None,
-        description="Dividend yield, as a normalized percent.",
-        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
-    )
     payout_ratio: Optional[float] = Field(default=None, description="Payout ratio")
     sales_general_and_administrative_to_revenue: Optional[float] = Field(
         default=None,
@@ -149,16 +173,6 @@ class FMPKeyMetricsData(KeyMetricsData):
     stock_based_compensation_to_revenue: Optional[float] = Field(
         default=None, description="Stock-based compensation-to-revenue ratio"
     )
-    graham_number: Optional[float] = Field(default=None, description="Graham number")
-    roic: Optional[float] = Field(
-        default=None, description="Return on invested capital"
-    )
-    return_on_tangible_assets: Optional[float] = Field(
-        default=None, description="Return on tangible assets"
-    )
-    graham_net_net: Optional[float] = Field(
-        default=None, description="Graham net-net working capital"
-    )
     working_capital: Optional[float] = Field(
         default=None, description="Working capital"
     )
@@ -168,6 +182,9 @@ class FMPKeyMetricsData(KeyMetricsData):
     net_current_asset_value: Optional[float] = Field(
         default=None, description="Net current asset value"
     )
+    enterprise_value: Optional[float] = Field(
+        default=None, description="Enterprise value"
+    )
     invested_capital: Optional[float] = Field(
         default=None, description="Invested capital"
     )
@@ -198,9 +215,32 @@ class FMPKeyMetricsData(KeyMetricsData):
     inventory_turnover: Optional[float] = Field(
         default=None, description="Inventory turnover"
     )
-    roe: Optional[float] = Field(default=None, description="Return on equity")
-    capex_per_share: Optional[float] = Field(
-        default=None, description="Capital expenditures per share"
+    return_on_equity: Optional[float] = Field(
+        default=None,
+        description="Return on equity",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+        alias="roe",
+    )
+    return_on_invested_capital: Optional[float] = Field(
+        default=None,
+        description="Return on invested capital",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+        alias="roic",
+    )
+    return_on_tangible_assets: Optional[float] = Field(
+        default=None,
+        description="Return on tangible assets",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+    )
+    dividend_yield: Optional[float] = Field(
+        default=None,
+        description="Dividend yield, as a normalized percent.",
+        json_schema_extra={"x-unit_measurement": "percent", "x-frontend_multiply": 100},
+        alias="dividendYield",
+    )
+    graham_number: Optional[float] = Field(default=None, description="Graham number")
+    graham_net_net: Optional[float] = Field(
+        default=None, description="Graham net-net working capital"
     )
 
 
@@ -210,7 +250,7 @@ class FMPKeyMetricsFetcher(
         List[FMPKeyMetricsData],
     ]
 ):
-    """Transform the query, extract and transform the data from the FMP endpoints."""
+    """FMP Key Metrics Fetcher."""
 
     @staticmethod
     def transform_query(params: Dict[str, Any]) -> FMPKeyMetricsQueryParams:
@@ -226,31 +266,34 @@ class FMPKeyMetricsFetcher(
         """Return the raw data from the FMP endpoint."""
         api_key = credentials.get("fmp_api_key") if credentials else ""
         base_url = "https://financialmodelingprep.com/api/v3"
-
         symbols = query.symbol.split(",")
-
         results: List = []
 
         async def get_one(symbol):
             """Get data for one symbol."""
-
-            url = f"{base_url}/key-metrics/{symbol}?period={query.period}&limit={query.limit}&apikey={api_key}"
-
+            url = (
+                f"{base_url}/key-metrics/{symbol}?period={query.period}"
+                + f"&limit={query.limit}&apikey={api_key}"
+            )
             result = await amake_request(
                 url, response_callback=response_callback, **kwargs
             )
-
             if not result:
                 warn(f"Symbol Error: No data found for {symbol}.")
 
             if result:
-
                 ttm_url = f"{base_url}/key-metrics-ttm/{symbol}?&apikey={api_key}"
                 if query.with_ttm and (
                     metrics_ttm := await amake_request(
                         ttm_url, response_callback=response_callback, **kwargs
                     )
                 ):
+                    metrics_ttm_data = {
+                        k: v
+                        for k, v in metrics_ttm[0].items()
+                        if k
+                        not in ("dividendYieldPercentageTTM", "dividendPerShareTTM")
+                    }
                     result.insert(  # type: ignore
                         0,
                         {
@@ -258,7 +301,10 @@ class FMPKeyMetricsFetcher(
                             "period": "TTM",
                             "date": datetime.now().strftime("%Y-%m-%d"),
                             "calendar_year": datetime.now().year,
-                            **{k.replace("TTM", ""): v for k, v in metrics_ttm.items()},  # type: ignore
+                            **{
+                                k.replace("TTM", ""): v
+                                for k, v in metrics_ttm_data.items()
+                            },
                         },
                     )
                 results.extend(result)
@@ -266,7 +312,7 @@ class FMPKeyMetricsFetcher(
         await asyncio.gather(*[get_one(symbol) for symbol in symbols])
 
         if not results:
-            raise EmptyDataError("No data found for given symbols.")
+            raise EmptyDataError(f"No data found for given symbols -> {query.symbol}.")
 
         return results