Metadata-Version: 2.5
Name: yfdata
Version: 0.2.4
Summary: Client for Yahoo Finance data
Author-email: "Andrea C." <andrea.cap.dev@icloud.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: curl-cffi>=0.15.0
Requires-Dist: pandas>=3.0.3
Description-Content-Type: text/markdown

# yf-data

![application-build](https://github.com/caps6/yf-data/actions/workflows/python-build.yml/badge.svg)
![PyPI - Downloads](https://img.shields.io/pypi/dm/yfdata)

A small Python client that returns normalized Yahoo Finance data as Pandas
DataFrames.

## Features

Available data include:

- OHLC values for stocks and exchange rates
- dividends
- company financial data from income and balance sheets

All results are returned as [Pandas DataFrames](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).

Temporal values follow their domain semantics:

| Data | Temporal value | Timezone rule |
|------|----------------|---------------|
| 1-minute stock prices | timezone-aware `pandas.Timestamp` | UTC |
| Daily stock prices | `datetime.date` | Exchange civil date; UTC fallback |
| Exchange rates (`1m` and `1D`) | timezone-aware `pandas.Timestamp` | UTC |
| Income and balance-sheet periods | `datetime.date` | Date reported by Yahoo |
| Dividends | `datetime.date` | Exchange civil date; UTC fallback |

The public API does not return naive datetimes.

## Usage

```python
from yfdata import YahooProvider

yp = YahooProvider()

# Frequency for prices and exchange rates can be daily ("1D") or 1-minute ("1m").

# Get daily OHLC data.
df = yp.get_prices(["aapl"], "1D")

# Get exchange rates with frequency of 1 minute.
df = yp.get_rates("usd", "eur", freq="1m")

# Get company dividends.
df = yp.get_dividends(["aapl", "msft"])

# Income frequency can be annual ("A"), quarterly ("Q"), or
# trailing twelve months ("TTM").

# Balance-sheet frequency can be annual ("A") or quarterly ("Q").

# Get annual income data.
df = yp.get_income(["aapl", "msft"], freq="A")

# Get quarterly balance data.
df = yp.get_balance(["aapl", "msft"], freq="Q")

# Define a list of specific metrics for income data.
metrics = ["total_revenue", "ebitda"]
df = yp.get_income(["aapl", "msft"], freq="A", metrics=metrics)
```

## Output examples

An excerpt from 1-minute OHLC price data:

| ticker | ts                        | o          | h          | l          | c          | v         |
|--------|---------------------------|------------|------------|------------|------------|-----------|
| aapl   | 2024-07-26 13:30:00+00:00 | 218.850006 | 219.149902 | 218.089996 | 218.740005 | 1170434.0 |
| aapl   | 2024-07-26 13:31:00+00:00 | 218.389999 | 218.470001 | 218.000000 | 218.020004 | 382342.0  |
| aapl   | 2024-07-26 13:32:00+00:00 | 218.054993 | 218.740005 | 218.020004 | 218.481903 | 227239.0  |
| aapl   | 2024-07-26 13:33:00+00:00 | 218.479996 | 218.539993 | 217.669998 | 217.669998 | 263403.0  |
| aapl   | 2024-07-26 13:34:00+00:00 | 217.630005 | 217.630005 | 217.119995 | 217.160004 | 241679.0  |

An excerpt from annual balance data:

| ticker | metric                 | freq | date       | value       |
|--------|------------------------|------|------------|-------------|
| aapl   | total_assets           | A    | 2020-09-30 | 3.23888e+11 |
| aapl   | total_assets           | A    | 2021-09-30 | 3.51002e+11 |
| aapl   | total_assets           | A    | 2022-09-30 | 3.52755e+11 |
| aapl   | total_assets           | A    | 2023-09-30 | 3.52583e+11 |
| aapl   | ordinary_shares_number | A    | 2020-09-30 | 1.69768e+10 |
| aapl   | ordinary_shares_number | A    | 2021-09-30 | 1.64268e+10 |
| aapl   | ordinary_shares_number | A    | 2022-09-30 | 1.59434e+10 |
| aapl   | ordinary_shares_number | A    | 2023-09-30 | 1.55501e+10 |

## Financial metrics

Available metrics for the income statement are:

- total_revenue
- cost_of_revenue
- gross_profit
- operating_expense
- operating_income
- non_operating_interest_income_expense
- other_income_expense
- basic_eps
- diluted_eps
- basic_average_shares
- total_expense
- normalized_income
- ebit
- ebitda

Available metrics for balance sheet are:

- total_assets
- total_liabilities_net_minority_interest
- total_equity_gross_minority_interest
- total_capitalization
- common_stock_equity
- capital_lease_obligations
- net_tangible_assets
- working_capital
- invested_capital
- tangible_book_value
- total_debt
- net_debt
- share_issued
- ordinary_shares_number
