0
# Single Ticker Data Access
1

2
Comprehensive data access for individual financial instruments. The `Ticker` class provides access to historical prices, financial statements, ownership data, analyst recommendations, options chains, and extensive company information.
3

4
## Capabilities
5

6
### Core Ticker Operations
7

8
Create ticker objects and access basic information for any financial instrument supported by Yahoo Finance.
9

10
```python { .api }
11
class Ticker:
12
    def __init__(self, ticker: str, session=None, proxy=None):
13
        """
14
        Create a Ticker object for accessing financial data.
15
        
16
        Parameters:
17
        - ticker: str, ticker symbol (e.g., "AAPL", "MSFT", "BTC-USD")
18
        - session: requests.Session, optional session for HTTP requests
19
        - proxy: deprecated, use yf.set_config(proxy=proxy) instead
20
        """
21
```
22

23
#### Usage Example
24

25
```python
26
import yfinance as yf
27

28
# Create ticker objects
29
apple = yf.Ticker("AAPL")
30
bitcoin = yf.Ticker("BTC-USD")
31
sp500 = yf.Ticker("^GSPC")
32

33
# Access basic info
34
print(apple.info['longName'])  # "Apple Inc."
35
print(apple.info['sector'])    # "Technology"
36
```
37

38
### Historical Price Data
39

40
Download historical price and volume data with flexible date ranges, intervals, and adjustment options.
41

42
```python { .api }
43
def history(self, period: str = "1mo", interval: str = "1d", 
44
           start: Union[str, datetime] = None, end: Union[str, datetime] = None,
45
           prepost: bool = False, actions: bool = True, auto_adjust: bool = True,
46
           repair: bool = False, **kwargs) -> pd.DataFrame:
47
    """
48
    Download historical market data.
49
    
50
    Parameters:
51
    - period: str, data period ("1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max")
52
    - interval: str, data interval ("1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo")
53
    - start: str/datetime, start date (YYYY-MM-DD format)
54
    - end: str/datetime, end date (YYYY-MM-DD format)
55
    - prepost: bool, include pre and post market data
56
    - actions: bool, include dividend and split data
57
    - auto_adjust: bool, adjust OHLC prices for splits and dividends
58
    - repair: bool, repair bad data points
59
    
60
    Returns:
61
    pd.DataFrame with columns: Open, High, Low, Close, Volume, Dividends, Stock Splits
62
    """
63
```
64

65
#### Usage Example
66

67
```python
68
ticker = yf.Ticker("AAPL")
69

70
# Get 1 year of daily data
71
data = ticker.history(period="1y")
72

73
# Get specific date range with hourly data
74
data = ticker.history(start="2023-01-01", end="2023-12-31", interval="1h")
75

76
# Get raw data without adjustments
77
data = ticker.history(period="6mo", auto_adjust=False, actions=False)
78
```
79

80
### Company Information
81

82
Access comprehensive company metadata, financial metrics, and key statistics.
83

84
```python { .api }
85
# Properties
86
info: dict  # Complete company information dictionary
87
fast_info: dict  # Quick access to essential price metrics
88
history_metadata: dict  # Metadata about historical data availability
89
isin: str  # International Securities Identification Number
90
```
91

92
#### Key Info Fields
93

94
The `info` dictionary contains extensive company data:
95

96
- **Basic Info**: `longName`, `shortName`, `symbol`, `sector`, `industry`
97
- **Financial Metrics**: `marketCap`, `enterpriseValue`, `trailingPE`, `forwardPE`
98
- **Price Data**: `currentPrice`, `dayHigh`, `dayLow`, `fiftyTwoWeekHigh`, `fiftyTwoWeekLow`
99
- **Share Data**: `sharesOutstanding`, `floatShares`, `impliedSharesOutstanding`
100
- **Valuation**: `bookValue`, `priceToBook`, `enterpriseToRevenue`, `enterpriseToEbitda`
101
- **Profitability**: `profitMargins`, `operatingMargins`, `returnOnAssets`, `returnOnEquity`
102
- **Growth**: `revenueGrowth`, `earningsGrowth`, `earningsQuarterlyGrowth`
103

104
### Financial Statements
105

106
Access annual, quarterly, and trailing twelve months (TTM) financial statement data.
107

108
```python { .api }
109
# Income Statement
110
income_stmt: pd.DataFrame  # Annual income statement
111
quarterly_income_stmt: pd.DataFrame  # Quarterly income statement
112
ttm_income_stmt: pd.DataFrame  # Trailing twelve months income statement
113
financials: pd.DataFrame  # Alias for income_stmt
114
quarterly_financials: pd.DataFrame  # Alias for quarterly_income_stmt
115
ttm_financials: pd.DataFrame  # Alias for ttm_income_stmt
116

117
# Balance Sheet
118
balance_sheet: pd.DataFrame  # Annual balance sheet
119
quarterly_balance_sheet: pd.DataFrame  # Quarterly balance sheet
120

121
# Cash Flow Statement
122
cash_flow: pd.DataFrame  # Annual cash flow statement
123
quarterly_cash_flow: pd.DataFrame  # Quarterly cash flow statement
124
ttm_cash_flow: pd.DataFrame  # Trailing twelve months cash flow
125
```
126

127
#### Usage Example
128

129
```python
130
ticker = yf.Ticker("AAPL")
131

132
# Get annual financial statements
133
income = ticker.income_stmt
134
balance = ticker.balance_sheet
135
cashflow = ticker.cash_flow
136

137
# Access specific metrics
138
revenue = income.loc['Total Revenue']
139
total_assets = balance.loc['Total Assets']
140
operating_cash_flow = cashflow.loc['Operating Cash Flow']
141

142
# Get quarterly data for recent periods
143
quarterly_revenue = ticker.quarterly_income_stmt.loc['Total Revenue']
144
```
145

146
### Earnings and Calendar
147

148
Access earnings data, estimates, and important calendar dates.
149

150
```python { .api }
151
# Earnings Data
152
earnings: pd.DataFrame  # Annual earnings data
153
quarterly_earnings: pd.DataFrame  # Quarterly earnings data
154
earnings_dates: pd.DataFrame  # Upcoming and historical earnings dates
155
calendar: dict  # Earnings and dividend calendar
156

157
# Usage Example
158
earnings_history = ticker.earnings
159
next_earnings = ticker.earnings_dates
160
upcoming_events = ticker.calendar
161
```
162

163
### Dividends and Corporate Actions
164

165
Access dividend history, stock splits, and other corporate actions.
166

167
```python { .api }
168
# Corporate Actions Properties
169
dividends: pd.Series  # Historical dividend payments
170
capital_gains: pd.Series  # Capital gains distributions (for funds)
171
splits: pd.Series  # Stock split history
172
actions: pd.DataFrame  # Combined dividends and splits data
173

174
# Share Data
175
shares: pd.DataFrame  # Basic shares outstanding data
176

177
def get_shares_full(self, start: Union[str, datetime] = None, 
178
                   end: Union[str, datetime] = None) -> pd.Series:
179
    """
180
    Get detailed historical shares outstanding data.
181
    
182
    Parameters:
183
    - start: str/datetime, start date
184
    - end: str/datetime, end date
185
    
186
    Returns:
187
    pd.Series with shares outstanding over time
188
    """
189
```
190

191
### Ownership and Insider Data
192

193
Access institutional ownership, mutual fund holdings, and insider trading information.
194

195
```python { .api }
196
# Ownership Properties
197
major_holders: pd.DataFrame  # Major institutional holders summary
198
institutional_holders: pd.DataFrame  # Detailed institutional ownership
199
mutualfund_holders: pd.DataFrame  # Mutual fund ownership
200
insider_purchases: pd.DataFrame  # Recent insider purchase transactions
201
insider_transactions: pd.DataFrame  # All insider transactions
202
insider_roster_holders: pd.DataFrame  # Current insider positions
203
```
204

205
### Analyst Data and Recommendations
206

207
Access analyst recommendations, price targets, earnings estimates, and research reports.
208

209
```python { .api }
210
# Analyst Data Properties
211
recommendations: pd.DataFrame  # Historical analyst recommendations
212
recommendations_summary: pd.DataFrame  # Current recommendations summary
213
upgrades_downgrades: pd.DataFrame  # Recent rating changes
214
analyst_price_targets: dict  # Price target statistics and distribution
215

216
# Earnings Estimates
217
earnings_estimate: pd.DataFrame  # Earnings per share estimates
218
revenue_estimate: pd.DataFrame  # Revenue estimates
219
earnings_history: pd.DataFrame  # Earnings surprise history
220
eps_trend: pd.DataFrame  # EPS estimate trends over time
221
eps_revisions: pd.DataFrame  # Recent EPS estimate revisions
222
growth_estimates: pd.DataFrame  # Long-term growth rate estimates
223
```
224

225
### Options Data
226

227
Access options chains, expiration dates, and derivatives information.
228

229
```python { .api }
230
# Options Properties
231
options: tuple  # Available options expiration dates
232

233
def option_chain(self, date: str = None, tz: str = None) -> namedtuple:
234
    """
235
    Get options chain data for a specific expiration date.
236
    
237
    Parameters:
238
    - date: str, expiration date in YYYY-MM-DD format (if None, uses nearest expiration)
239
    - tz: str, timezone for option data
240
    
241
    Returns:
242
    namedtuple with attributes:
243
    - calls: pd.DataFrame with call options data
244
    - puts: pd.DataFrame with put options data  
245
    - underlying: dict with underlying stock info
246
    """
247
```
248

249
#### Usage Example
250

251
```python
252
ticker = yf.Ticker("AAPL")
253

254
# Get available expiration dates
255
expirations = ticker.options
256
print(expirations)  # ('2024-01-19', '2024-01-26', ...)
257

258
# Get options chain for specific date
259
chain = ticker.option_chain('2024-01-19')
260
calls = chain.calls
261
puts = chain.puts
262
underlying = chain.underlying
263

264
# Filter options by criteria
265
otm_calls = calls[calls['inTheMoney'] == False]
266
high_volume_puts = puts[puts['volume'] > 100]
267
```
268

269
### Additional Data Sources
270

271
Access news, ESG data, SEC filings, and mutual fund specific information.
272

273
```python { .api }
274
# Additional Properties
275
news: list  # Recent news articles related to the ticker
276
sustainability: pd.DataFrame  # ESG (Environmental, Social, Governance) scores
277
sec_filings: dict  # SEC filing information and links
278
funds_data: FundsData  # Mutual fund/ETF specific data (if applicable)
279
```
280

281
### Real-time Streaming
282

283
Enable real-time data streaming for individual tickers.
284

285
```python { .api }
286
def live(self, message_handler: Callable = None, verbose: bool = True):
287
    """
288
    Start real-time data streaming for this ticker.
289
    
290
    Parameters:
291
    - message_handler: function to handle incoming messages
292
    - verbose: bool, enable verbose logging
293
    """
294
```
295

296
#### Usage Example
297

298
```python
299
def handle_price_update(message):
300
    print(f"Price update: {message}")
301

302
ticker = yf.Ticker("AAPL")
303
ticker.live(message_handler=handle_price_update)
304
```
305

306
## Data Types and Formats
307

308
### DataFrame Structures
309

310
**Historical Data DataFrame**:
311
- Index: DatetimeIndex
312
- Columns: Open, High, Low, Close, Volume, Dividends, Stock Splits
313

314
**Financial Statements DataFrames**:
315
- Index: Financial line items (e.g., 'Total Revenue', 'Net Income')
316
- Columns: Date periods (most recent first)
317

318
**Options DataFrames**:
319
- Columns: contractSymbol, strike, currency, lastPrice, change, percentChange, volume, openInterest, bid, ask, contractSize, expiration, lastTradeDate, impliedVolatility, inTheMoney
320

321
### Common Patterns
322

323
```python
324
# Check if data exists before using
325
if not ticker.info:
326
    print("No info available")
327

328
if ticker.history().empty:
329
    print("No historical data available")
330

331
# Handle missing data gracefully
332
try:
333
    financials = ticker.income_stmt
334
    if not financials.empty:
335
        revenue = financials.loc['Total Revenue'].iloc[0]
336
except (KeyError, IndexError):
337
    print("Revenue data not available")
338
```