fmp-py 0.0.20.3
Python package for Financial Modeling Prep API
Requires Python: <4.0,>=3.10

<p align="center">
  <img src="https://raw.githubusercontent.com/PKief/vscode-material-icon-theme/ec559a9f6bfd399b82bb44393651661b08aaf7ba/icons/folder-markdown-open.svg" width="100" alt="project-logo">
</p>
<p align="center">
    <h1 align="center">FMP-PY</h1>
</p>
<p align="center">
    <em>Unlock Financial Insights with Seamless API Integration</em>
</p>
<p align="center">
   <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/TexasCoding/py-alpaca-api/.github%2Fworkflows%2Ftest-package.yaml">
	<img src="https://img.shields.io/github/license/TexasCoding/fmp-py?style=flat-square&logo=opensourceinitiative&logoColor=white&color=0080ff" alt="license">
	<img src="https://img.shields.io/github/last-commit/TexasCoding/fmp-py?style=flat-square&logo=git&logoColor=white&color=0080ff" alt="last-commit">
	<img src="https://img.shields.io/github/languages/top/TexasCoding/fmp-py?style=flat-square&color=0080ff" alt="repo-top-language">
	<img src="https://img.shields.io/github/languages/count/TexasCoding/fmp-py?style=flat-square&color=0080ff" alt="repo-language-count">
<p>
<p align="center">
		<em>Developed with the software and tools below.</em>
</p>
<p align="center">
	<img src="https://img.shields.io/badge/precommit-FAB040.svg?style=flat-square&logo=pre-commit&logoColor=black" alt="precommit">
	<img src="https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white" alt="Poetry">
	<img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white" alt="Python">
	<img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white" alt="GitHub%20Actions">
	<img src="https://img.shields.io/badge/pandas-150458.svg?style=flat-square&logo=pandas&logoColor=white" alt="pandas">
</p>

<br><!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents</summary><br>

- [ Overview](#-overview)
- [ Features](#-features)
- [ Repository Structure](#-repository-structure)
- [ Modules](#-modules)
- [ Getting Started](#-getting-started)
  - [ Installation](#-installation)
  - [ Usage](#-usage)
  - [ Tests](#-tests)
- [ Project Roadmap](#-project-roadmap)
- [ Contributing](#-contributing)
- [ License](#-license)
- [ Acknowledgments](#-acknowledgments)
</details>
<hr>

##  Overview

The `fmp-py` project is a comprehensive Python library designed to interface with the [Financial Modeling Prep (FMP) API](https://site.financialmodelingprep.com/), enabling seamless retrieval and analysis of a wide array of financial data. Core functionalities include accessing historical and intraday stock prices, company information, IPO calendars, mergers and acquisitions, stock splits, earnings reports, dividends, forex, and cryptocurrency data. It provides well-structured data models and methods to fetch, process, and integrate various financial metrics, enhancing users ability to perform detailed financial market analyses and make informed investment decisions efficiently.

[Documentation](https://fmp-py.readthedocs.io/en/latest/index.html)
---

##  Features

|    |   Feature         | Description |
|----|-------------------|---------------------------------------------------------------|
| ⚙️  | **Architecture**  | The project follows a modular architecture with separate files for different financial data functionalities, aiding in maintainability and scalability. |
| 🔩 | **Code Quality**  | The code adheres to consistent coding standards and practices with a focus on maintainability and readability, supported by pre-commit hooks and ruff for linting. |
| 📄 | **Documentation** | The project includes comprehensive documentation generated by Sphinx, with themes like `sphinx-rtd-theme`. Documentation covers usage and API reference. |
| 🔌 | **Integrations**  | Integrates with Financial Modeling Prep API for financial data. Utilizes GitHub Actions for continuous integration to automate testing workflows. |
| 🧩 | **Modularity**    | Highly modular with well-defined interfaces. Modules can be easily reused and extended, facilitating integration in various financial applications. |
| 🧪 | **Testing**       | Uses `requests-mock` for mocking API requests in tests. GitHub Actions are used for automating the test execution. |
| ⚡️  | **Performance**   | Efficiently handles API requests with caching via `requests-cache` and rate-limiting through `requests-ratelimiter` to optimize performance. |
| 🛡️ | **Security**      | Employs `python-dotenv` for secure management of environment variables, ensuring API keys and sensitive information are protected. |
| 📦 | **Dependencies**  | Key dependencies include `requests`, `pandas`, `pendulum`, `sphinx`, `requests-cache`, and `requests-ratelimiter` among others, as specified in `pyproject.toml`. |
| 🚀 | **Scalability**   | Designed to scale with increased API request loads, thanks to efficient use of caching, rate limiting, and modular architecture. |

---

##  Repository Structure

```sh
└── fmp-py
    ├── src
    │   └── fmp_py
    │       ├── __init__.py
    │       ├── fmp_base.py
    │       ├── fmp_chart_data.py
    │       ├── fmp_company_information.py
    │       ├── fmp_company_search.py
    │       ├── fmp_crypto.py
    │       ├── fmp_dividends.py
    │       ├── fmp_earnings.py
    │       ├── fmp_financial_statements.py
    │       ├── fmp_forex.py
    │       ├── fmp_historical_data.py
    │       ├── fmp_ipo_calendar.py
    │       ├── fmp_mergers_and_aquisitions.py
    │       ├── fmp_price_targets.py
    │       ├── fmp_quote.py
    │       ├── fmp_splits.py
    │       ├── fmp_statement_analysis.py
    │       ├── fmp_stock_list.py
    │       ├── fmp_upgrades_downgrades.py
    │       ├── fmp_valuation.py
    │       └── models
    │           ├── company_information.py
    │           ├── price_targets.py
    │           ├── quote.py
    │           ├── statement_analysis.py
    │           ├── upgrades_downgrades.py
    │           └── valuation.py
    └── tests
        ├── __init__.py
        ├── test_fmp_chart_data.py
        ├── test_fmp_company_information.py
        ├── test_fmp_company_search.py
        ├── test_fmp_crypto.py
        ├── test_fmp_dividends.py
        ├── test_fmp_earnings.py
        ├── test_fmp_financial_statements.py
        ├── test_fmp_forex.py
        ├── test_fmp_historical_data.py
        ├── test_fmp_ipo_calendar.py
        ├── test_fmp_mergers_and_aquisitions.py
        ├── test_fmp_price_targets.py
        ├── test_fmp_quote.py
        ├── test_fmp_splits.py
        ├── test_fmp_statement_analysis.py
        ├── test_fmp_stock_list.py
        ├── test_fmp_upgrades_downgrades.py
        └── test_fmp_valuation.py
```

---

##  Modules

<details closed><summary>.</summary>

| File                                                                               | Summary                                                                                                                                                                                                                                                                                                                                                 |
| ---                                                                                | ---                                                                                                                                                                                                                                                                                                                                                     |
| [pyproject.toml](https://github.com/TexasCoding/fmp-py/blob/master/pyproject.toml) | Define the project metadata, dependencies, and configurations for the fmp-py package, facilitating structured development, testing, and documentation. The specified settings enhance compatibility, style consistency, and build management, ensuring smooth integration and maintainability within the Financial Modeling Prep APIs Python interface. |

</details>

<details closed><summary>src.fmp_py</summary>

| File                                                                                                                          | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---                                                                                                                           | ---                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [fmp_upgrades_downgrades.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_upgrades_downgrades.py)         | Retrieve and process stock upgrade and downgrade data from the Financial Modeling Prep API, providing methods for obtaining consensus data, company-specific upgrades/downgrades, and RSS feed updates, ensuring comprehensive and up-to-date financial insights.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [fmp_financial_statements.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_financial_statements.py)       | Summary of the Code FileThe code file is part of the `fmp-py` repository, which provides a Python interface for interacting with various financial data APIs. The key purpose of this specific file is to facilitate interactions with a particular financial endpoint (e.g., historical data, company information, forex, etc.), effectively leveraging the base functionalities established across the repository. Critical features likely include methods for fetching, processing, and returning financial data in a structured format, enabling users to easily integrate this information into their applications. This file is integral to the repositorys architecture, as it extends the overall capability to cater to diverse financial data needs, contributing to a comprehensive Python package for financial market data analysis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [fmp_ipo_calendar.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_ipo_calendar.py)                       | Retrieve IPO calendar data, including symbol-specific information, IPO prospectus details, and confirmed IPOs within a specified date range. Integrate seamlessly with the Financial Modeling Prep API to provide structured DataFrames facilitating financial data analysis for users.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [fmp_mergers_and_aquisitions.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_mergers_and_aquisitions.py) | Provides methods to retrieve and process mergers and acquisitions data from the Financial Modeling Prep API, offering search capabilities by company name and fetching data from an RSS feed, thereby enhancing the overall data retrieval functionality within the repositorys architecture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [fmp_splits.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_splits.py)                                   | Retrieve and organize historical and calendar stock splits data from the Financial Modeling Prep API, aiding users in accessing detailed information about stock split events within specified date ranges and for specific stock symbols.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [fmp_chart_data.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_chart_data.py)                           | The file `fmp_financial_statements.py` within the `fmp-py` repository is pivotal for providing functionalities related to financial statements. It focuses on retrieving, processing, and presenting financial data such as balance sheets, income statements, and cash flow statements for various companies. This module is a critical component of the broader architecture as it interfaces with the financial data provider and ensures that users can access and utilize up-to-date financial information efficiently. The seamless integration and utility of this module highlight its importance in the repositorys goal of offering comprehensive financial data analysis and access tools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [fmp_company_search.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_company_search.py)                   | Provide methods to search for companies in the Financial Modeling Prep (FMP) API using various identifiers such as ISIN, CUSIP, CIK, ticker symbols, and company names. Integrates search functionality into the broader architecture for retrieving and processing financial data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [fmp_historical_data.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_historical_data.py)                 | Facilitates retrieval and preparation of historical financial data from Financial Modeling Prep API, including daily and intraday stock prices. Enhances data with calculated metrics like VWAP, and ensures data consistency through date sorting and price rounding, contributing to the repositorys comprehensive financial data analysis capabilities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [fmp_quote.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_quote.py)                                     | Summary of the Code Files Purpose and FeaturesThe `fmp_chart_data.py` file is a crucial component of the **fmp-py** repository, which appears to facilitate interaction with financial data, likely sourced from an external API. This specific file is dedicated to handling chart data, providing functions and utilities to fetch, process, and manage various types of financial charts. As part of the broader `src/fmp_py` directory, it integrates seamlessly with other modules, such as those dealing with company information, historical data, and financial statements, contributing to a comprehensive toolkit for financial data analysis. This integration enhances the repositorys capability to offer a robust and versatile framework for users looking to perform detailed and diverse financial analyses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [fmp_statement_analysis.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_statement_analysis.py)           | The `fmp_company_search.py` file is part of the `fmp-py` repository, specifically located within the `src/fmp_py` directory. This file primarily facilitates the searching of company information using specific criteria, enabling users to retrieve relevant data about companies based on various parameters. The critical features include functionalities for querying and filtering company data, which are essential components for users needing detailed and tailored company information within the larger scope of financial data management that the repository aims to provide. By integrating these search capabilities, the file significantly enhances the repositorys utility in handling comprehensive financial data operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [fmp_company_information.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_company_information.py)         | Fmp-pyThe code file is part of the `fmp-py` repository, which appears to be a Python package focused on financial market data integration. This package is structured into several modules, each targeting specific aspects of financial data, such as company information, crypto, forex, historical data, earnings, dividends, etc. ### Main Purpose of the Code FileThe primary purpose of this code file is to provide functionalities related to one of the specialized areas within financial market data (e.g., company information, earnings, or historical data). It serves as a module that users can import and utilize to retrieve, process, and manipulate the relevant financial data efficiently.### Critical Features-**ModularityThe code file is designed as a discrete module within the `src/fmp_py` directory, encapsulating specific functionalities and ensuring that related tasks are organized logically and cohesively.-**IntegrationIt integrates seamlessly with other modules in the repository to offer a comprehensive and unified API for financial market data.-**ConvenienceProvides user-friendly methods to access and handle complex financial data operations, making it easier for users to implement and use in their projects.In summary, this code file plays a critical role in the modular architecture of the `fmp-py` repository, focusing on delivering specialized financial market data functionalities that integrate with the overall package to offer a robust and comprehensive solution. |
| [fmp_valuation.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_valuation.py)                             | Summary of `fmp_mergers_an.py` in Relation to the RepositoryThe `fmp_mergers_an.py` file, located within the `src/fmp_py` directory of the `fmp-py` repository, is designed to handle the extraction and manipulation of financial data related to mergers and acquisitions. As part of the broader architecture, this file specifically focuses on providing functionality to access and process market information pertaining to corporate mergers and acquisitions. This capability is complementary to the other modules within the directory, which collectively offer a comprehensive suite for interacting with various financial market data, including company information, historical data, earnings, dividends, and more. The purpose of `fmp_mergers_an.py` is thus to enrich the repositorys overall utility by adding specialized data handling for mergers and acquisitions, thereby enabling users to perform detailed financial analyses and make informed decisions based on the latest market activities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [fmp_earnings.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_earnings.py)                               | Facilitates retrieving earnings data from the Financial Modeling Prep API, encompassing earnings surprises, confirmed earnings, earnings calendars, historical earnings, and checks for upcoming earnings within specified weeks. Integrates seamlessly within the broader architecture, aiding in comprehensive financial data analysis and decision-making.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [fmp_base.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_base.py)                                       | Facilitates API communication with Financial Modeling Prep by managing requests and handling retries. Provides methods for data cleaning and error handling, ensuring robust and reliable API interactions within the larger repository architecture. Essential for implementing consistent and efficient API calls throughout the modules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [fmp_stock_list.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_stock_list.py)                           | Implements the FmpStockList class to interface with the Financial Modeling Prep API, retrieving comprehensive stock and ETF lists, symbol changes, and various market data. Integrates seamlessly with the repositorys architecture, supporting robust data extraction and manipulation for financial analysis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [fmp_forex.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_forex.py)                                     | Retrieve and manage comprehensive forex market data, including daily and intraday quotes, full forex quotes, and lists of available forex pairs. Integrate seamlessly with the parent repositorys architecture to streamline financial data operations, ensuring up-to-date and accurate information for forex trading analysis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [fmp_crypto.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_crypto.py)                                   | Facilitate access to cryptocurrency data by providing functions to retrieve daily, intraday, and full crypto quotes, as well as a list of available cryptocurrencies. Integrates with the repositorys architecture to enhance financial market data analysis and support comprehensive financial modeling and prediction capabilities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [fmp_price_targets.py](https://github.com/TexasCoding/fmp-py/blob/master/src/fmp_py/fmp_price_targets.py)                     | Provides methods to retrieve price target data from the Financial Modeling Prep API, including consensus, summary, and detailed price targets for specific stocks. Integrates with the repositorys architecture by leveraging a base class for API interactions and returning structured data models and DataFrame outputs.