spgmi_api_sdk 3.0.0
Module for Python sdk distribution
Requires Python: <4.0.0,>=3.9.0

# SPGMI CIQ Python Library

This library provides functions to authenticate users, retrieve financial data, and fetch market data. It supports three main services: Authentication, Financial Services, and Market Data Services.

## Features

#### 1. Authentication Services:

- Authenticate users with username and password.
- Generate an access token for authenticating services.
- Use refresh tokens to obtain new access tokens without re-authenticating.

#### 2. Financial Services:

- Retrieve point-in-time and historical income statements.
- Fetch current and historical balance sheet data.
- Access point-in-time and historical cash flow statements.
- Retrieve financial data based on specified mnemonics for specific metrics.

#### 3. Market Data Services:

- Fetch point-in-time and time-series pricing data for financial instruments.
- Obtain point-in-time and time-series dividend data.
- Retrieve point-in-time and time-series market metrics for specified identifiers.

#### 4. Proxy Support:

- Ability to use proxy objects for enhanced network communication.

#### 5. Data Format:

- Functions return data in the form of pandas DataFrames, facilitating easy data manipulation and analysis.


## Installation:


- You can install the package using pip. Ensure you have Python 3.12+ installed.


```sh

pip install "<path_to_sdk>/spgmi_api_sdk_python-2.0.0"
```


## Setting up the library
Using the below code, you can make the necessary imports and set up the required instances to use the Python library.

```sh
from IPython.core.display_functions import display
from spgmi_api_sdk.authentication.services import SDKAuthenticateServices
from spgmi_api_sdk.financials.services import SDKFinancialServices
from spgmi_api_sdk.marketdata.services import SDKMarketDataServices
from spgmi_api_sdk.corporatedata.services import SDKCorporateDataServices
from spgmi_api_sdk.kensho.services import SDKKenshoServices
from spgmi_api_sdk.esgscores.services import SDKEsgScoresServices

#Required Instances
auth = SDKAuthenticateServices()
fs= SDKFinancialServices()
mds = SDKMarketDataServices()
cds=SDKCorporateDataServices()
ks = SDKKenshoServices()
esg = SDKEsgScoresServices()
```
## Authentication Service
These functions provide a seamless authentication process to securely access API services. Included are the methods for obtaining and refreshing access tokens while ensuring all API requests are properly authorized.

### get_token()
```sh
username = "--username--"    #Replace with actual username
password = "--password--"    #Replace with actual password
token_response = auth.get_token(username, password)
bearer_token = token_response.get("access_token")
```
### get_refresh_token()
```sh
refresh_token_response=auth.get_refresh_token("--refresh_token--")
refresh_bearer_token = refresh_token_response.get("access_token")
```
## Fetching Financial Data
Our financial data service provides a number of functionalities enabling you to retrieve point-in-time and historical financial data including income statements, balance sheets, cash flow statements, and other financial metrics essential for comprehensive financial analysis. 

Use the following functions from the SDKFinancialServices class.

Note: All SDKFinancialServices functions will accept a maximum of 10 identifiers.

### 1. get_income_statement_pit
Fetches income statement data for a given point in time.
```sh
response = fs.get_income_statement_pit(token=bearer_token, identifiers=["I_US5949181045","2588173","EG1320"],properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)
```

### 2. get_income_statement_historical
Fetches historical income statement data.
```sh
response = fs.get_income_statement_historical(token=bearer_token, identifiers=["GV012141","MSFT:NasdaqGS"], properties={"periodType":"IQ_FQ-4"})
display(response)
```

### 3. get_balance_sheet_pit
Fetches balance sheet data for a given point in time.
```sh
response = fs.get_balance_sheet_pit(token=bearer_token, identifiers=["RX309198","MMM:"], properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)
```
### 4. get_balance_sheet_historical
Fetches historical balance sheet data.
```sh
response = fs.get_balance_sheet_historical(token=bearer_token, identifiers=["I_US5949181045","2588173"], properties={"periodType":"IQ_FQ-2"})
display(response)
```

### 5. get_cash_flow_pit
Fetches cash flow data for a given point in time.
```sh
response = fs.get_cash_flow_pit(token=bearer_token, identifiers=["2588173","EG1320"], properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)
```

### 6. get_cash_flow_historical
Fetches historical cash flow data.
```sh
response = fs.get_cash_flow_historical(token=bearer_token, identifiers=["MSFT:NasdaqGS","DB649496569"], properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)
```

### 7. get_financials_pit
Fetches financial data (income statement, balance sheet, cash flow) for a given point in time based on specified mnemonics. This function will accept a maximum of 10 mnemonics.
```sh
response = fs.get_financials_pit(token=bearer_token, identifiers=["I_US5949181045","2588173","EG1320","CSP_594918104","IQT2630413","GV012141","MSFT:NasdaqGS","DB649496569","RX309198"], mnemonics=["IQ_CASH_INVEST_NAME_AP"], properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)

```
### 8. get_financials_historical
Fetches historical financial data based on specified mnemonics. This function will accept a maximum of 10 mnemonics.
```sh
response = fs.get_financials_historical(token=bearer_token, identifiers=["I_US5949181045","2588173","EG1320","CSP_594918104","IQT2630413","GV012141","MSFT:NasdaqGS","DB649496569","RX309198"], mnemonics=["IQ_CASH_INVEST_NAME_AP"], properties={"asOfDate": "12/31/2020", "currencyId": "USD","currencyConversionModeId": "HISTORICAL"})
display(response)
```

### 8. get_financials
Fetches financial highlights, including key metrics for comprehensive analysis.
```sh
response = fs.get_financials(token=bearer_token, identifiers=["IQ21835","IQ26642","MSFT"],period_type="IQ_FY-1")
display(response)
```

## Fetching MarketData
Our market data service provides several functionalities enabling you to access end-of-day and time-series market data, including stock prices, trading volumes, dividend information, and other market-related information crucial for analysis and decision-making.

Use the following functions from the SDKMarketDataServices class.

Note: All SDKMarketDataServices functions will accept a maximum of 10 identifiers.

### 1. get_pricing_info_pit
Fetches pricing information for a given point in time.
```sh
response = mds.get_pricing_info_pit(token=bearer_token, identifiers=["I_US5949181045","2588173","EG1320","CSP_594918104","IQT2630413"], properties={}) 
display(response)
```

### 2. get_pricing_info_time_series
Fetches historical pricing information over a specified time period. 
```sh
response = mds.get_pricing_info_time_series(token=bearer_token, identifiers=["CSP_594918104","IQT2630413","GV012141","MSFT:NasdaqGS","DB649496569","RX309198","MMM:"], properties={}) 
display(response)
```

### 3. get_dividend_info_pit
Fetches dividend information for a given point in time. 
```sh
response = mds.get_dividend_info_pit(token=bearer_token, identifiers=["CSP_594918104","IQT2630413","GV012141","MSFT:NasdaqGS"], properties={}) 
display(response)
```

### 4. get_dividend_info_time_series
Fetches historical dividend information over a specified time period 
```sh
response = mds.get_dividend_info_time_series(token=bearer_token, identifiers=["GV012141","MSFT:NasdaqGS","DB649496569","RX309198","MMM:"], properties={}) 
display(response)
```

### 5. get_market_info_pit
Fetches market information for a given point in time. 
```sh
response = mds.get_market_info_pit(token=bearer_token, identifiers=["IQT2630413","GV012141","MSFT:NasdaqGS","DB649496569","RX309198"], properties={}) 
display(response)
```
### 6. get_market_info_time_series
Fetches historical market information over a specified time period.
```sh 
response = mds.get_market_info_time_series(token=bearer_token, identifiers=["AAPL:"], properties={}) 
display(response)
```

### 6. get_market_data
Fetches various market data metrics such as closing price, VWAP, open price, day high/low, and others.
```sh 
response=mds.get_market_data(token=bearer_token,identifiers=["IQ112350","MSFT","IQ24937"])
display(response)
```

## Fetching CorporateData
Our corporate data service provides functionalities to retrieve a wide range of corporate information, including company status, industry classifications, IPO Date, Industry Details and more.

Use the following functions from the SDKCorporateDataServices class.

### 1. get_corporate_data
Fetches corporate data metrics such as company status, industry classification, incorporation date, and more.
```sh 
response=cds.get_corporate_data(token=bearer_token,identifiers=["IQ112350","SPGI","IQ24937"])
display(response)
```


## Fetching ESG Scores
Our ESG Scores service provides functionalities to retrieve  detailed Environmental, Social, and Governance (ESG) scores.

Use the following function from the SDKEsgScoresServices class.

### 1. get_esg_scores
Fetches comprehensive ESG data, including environmental, social, and governance scores, along with associated metrics such as carbon emissions, human rights, business ethics, and more.
```sh 
response=esg.get_esg_scores(token=bearer_token,identifiers=["SNL4202062", "RX309198"],assessment_year= ["2022","2023"])
display(response)
```
## Company Name Search 
Our Company Name Search services allow you to fetch Capital IQ ID or MI Institution ID based on the company names.

### 1. get_company_name_to_id
Fetches Capital IQ IDs or MI Institution IDs for a list of given company names, helping in identifying companies by their recognized identifiers.
```sh 
response=ks.get_company_name_to_id(token=bearer_token, companies=["Coca Cola", "Meezan Bank Limited (MEBL)"])
display(response)
```
## Best Practice
```sh
# Best Practice: Secure Credential Management in Jupyter or DataBricks Notebooks
# Store and Retrieve Credentials from a .env File

import os
from dotenv import load_dotenv

# Ensure the .env file is placed in the notebook directory
load_dotenv('py.env')  # Replace 'py.env' with your .env file name if different

# Retrieve API credentials securely
api_username = os.getenv('SDKUSERNAME')  # replace with actual variable which is defined in .env file
api_password = os.getenv('SDKPASSWORD')

# Optional: Check if credentials are correctly retrieved from .env file
# print(api_username)

# Now you can use 'api_username' and 'api_password' in your code securely
# username = api_username    
# password = api_password
```
## Proxy (optional)
```sh
from spgmi_api_sdk.dataservices.model.sdk_proxy import SDKProxy
sdk_proxy_object = SDKProxy(proxy_username="", proxy_password="", proxy_host=None, proxy_port=None, proxy_domain="")
#usage of proxy in all function calls
#token_response = auth_services.get_token(username, password, proxy=sdk_proxy_object)
```

## Note:
Jupyter or Databricks Notebooks:
To display the response in notebooks, use the following command:
```sh
display(response)
```
PyCharm or Other IDEs:
To display the response in IDEs, use the following command:
```sh
display(response.data)
```