0
# Market Data & Research
1

2
Extensive market data access including real-time quotes, historical price data, news, analyst ratings, financial statements, and institutional holdings across stocks, options, and cryptocurrencies.
3

4
## Capabilities
5

6
### Real-time Quotes
7

8
Get current market prices and basic quote information for stocks and other securities.
9

10
```python { .api }
11
def get_quote(self, stock=None, tId=None):
12
    """
13
    Get real-time quote for a security.
14
    
15
    Parameters:
16
    - stock (str, optional): Stock symbol (e.g., 'AAPL')
17
    - tId (int, optional): Ticker ID (alternative to stock symbol)
18
    
19
    Returns:
20
    dict: Quote data including open, high, low, close, volume, change, changeRatio
21
    
22
    Raises:
23
    ValueError: If neither stock nor tId provided, or if symbol not found
24
    """
25
```
26

27
Usage example:
28

29
```python
30
# Get quote by symbol
31
quote = wb.get_quote(stock='AAPL')
32
print(f"AAPL: ${quote['close']} ({quote['changeRatio']}%)")
33

34
# Get quote by ticker ID
35
quote = wb.get_quote(tId=913256135)
36
```
37

38
### Ticker Information & Search
39

40
Get ticker metadata and search for securities by symbol.
41

42
```python { .api }
43
def get_ticker(self, stock=''):
44
    """
45
    Get ticker ID from stock symbol.
46
    
47
    Parameters:
48
    - stock (str): Stock symbol to look up
49
    
50
    Returns:
51
    int: Ticker ID for the symbol
52
    
53
    Raises:
54
    ValueError: If stock symbol not provided or not found
55
    """
56

57
def get_ticker_info(self, stock=None, tId=None):
58
    """
59
    Get detailed ticker information and metadata.
60
    
61
    Parameters:
62
    - stock (str, optional): Stock symbol
63
    - tId (int, optional): Ticker ID
64
    
65
    Returns:
66
    dict: Detailed ticker information including name, exchange, currency, etc.
67
    """
68

69
def get_all_tickers(self, region_code=None):
70
    """
71
    Get list of all available tickers for a region.
72
    
73
    Parameters:
74
    - region_code (str, optional): Region code (defaults to user's region)
75
    
76
    Returns:
77
    list: List of all available tickers with metadata
78
    """
79
```
80

81
Usage examples:
82

83
```python
84
# Convert symbol to ticker ID
85
ticker_id = wb.get_ticker('AAPL')
86
print(f"AAPL ticker ID: {ticker_id}")
87

88
# Get detailed ticker information
89
info = wb.get_ticker_info(stock='AAPL')
90
print(f"Company: {info['name']}")
91

92
# Get all available US tickers
93
all_tickers = wb.get_all_tickers(region_code='US')
94
```
95

96
### Historical Price Data
97

98
Retrieve historical price bars and chart data with various time intervals.
99

100
```python { .api }
101
def get_bars(self, stock=None, tId=None, interval='m1', count=1, extendTrading=0, timeStamp=None):
102
    """
103
    Get historical price bars for stocks.
104
    
105
    Parameters:
106
    - stock (str, optional): Stock symbol
107
    - tId (int, optional): Ticker ID
108
    - interval (str): Time interval - 'm1', 'm5', 'm15', 'm30', 'h1', 'h2', 'h4', 'd1', 'w1'
109
    - count (int): Number of bars to retrieve
110
    - extendTrading (int): Include extended hours data (0=no, 1=yes)
111
    - timeStamp (int, optional): Start timestamp for historical data
112
    
113
    Returns:
114
    list: List of price bars with open, high, low, close, volume, timestamp
115
    """
116

117
def get_bars_crypto(self, stock=None, tId=None, interval='m1', count=1, extendTrading=0, timeStamp=None):
118
    """
119
    Get historical price bars for cryptocurrencies.
120
    
121
    Parameters:
122
    - stock (str, optional): Crypto symbol (e.g., 'BTCUSD')
123
    - tId (int, optional): Ticker ID
124
    - interval (str): Time interval - 'm1', 'm5', 'm15', 'm30', 'h1', 'h2', 'h4', 'd1', 'w1'
125
    - count (int): Number of bars to retrieve
126
    - extendTrading (int): Include 24/7 data for crypto
127
    - timeStamp (int, optional): Start timestamp
128
    
129
    Returns:
130
    list: List of crypto price bars
131
    """
132

133
def get_chart_data(self, stock=None, tId=None, ma=5, timestamp=None):
134
    """
135
    Get chart data with moving averages.
136
    
137
    Parameters:
138
    - stock (str, optional): Stock symbol
139
    - tId (int, optional): Ticker ID
140
    - ma (int): Moving average period
141
    - timestamp (int, optional): Chart timestamp
142
    
143
    Returns:
144
    dict: Chart data with price and moving average information
145
    """
146
```
147

148
Usage examples:
149

150
```python
151
# Get daily bars for last 30 days
152
daily_bars = wb.get_bars(
153
    stock='AAPL',
154
    interval='d1',
155
    count=30
156
)
157

158
# Get 5-minute bars with extended hours
159
minute_bars = wb.get_bars(
160
    stock='TSLA',
161
    interval='m5',
162
    count=100,
163
    extendTrading=1
164
)
165

166
# Get crypto data (24/7 available)
167
crypto_bars = wb.get_bars_crypto(
168
    stock='BTCUSD',
169
    interval='h1',
170
    count=24
171
)
172
```
173

174
### News & Press Releases
175

176
Access news articles and press releases for securities and market events.
177

178
```python { .api }
179
def get_news(self, stock=None, tId=None, Id=0, items=20):
180
    """
181
    Get news articles for a security.
182
    
183
    Parameters:
184
    - stock (str, optional): Stock symbol
185
    - tId (int, optional): Ticker ID
186
    - Id (int): Starting news ID for pagination
187
    - items (int): Number of news items to retrieve
188
    
189
    Returns:
190
    list: List of news articles with title, summary, source, timestamp, URL
191
    """
192

193
def get_press_releases(self, stock=None, tId=None, typeIds=None, num=50):
194
    """
195
    Get press releases for a security.
196
    
197
    Parameters:
198
    - stock (str, optional): Stock symbol
199
    - tId (int, optional): Ticker ID
200
    - typeIds (list, optional): Filter by press release type IDs
201
    - num (int): Number of press releases to retrieve
202
    
203
    Returns:
204
    list: List of press releases
205
    """
206
```
207

208
Usage examples:
209

210
```python
211
# Get latest news for Apple
212
news = wb.get_news(stock='AAPL', items=10)
213
for article in news:
214
    print(f"{article['title']} - {article['sourceName']}")
215

216
# Get press releases
217
releases = wb.get_press_releases(stock='AAPL', num=5)
218
```
219

220
### Financial Analysis & Ratings
221

222
Access analyst ratings, financial analysis, and institutional data.
223

224
```python { .api }
225
def get_analysis(self, stock=None):
226
    """
227
    Get analyst ratings and analysis data.
228
    
229
    Parameters:
230
    - stock (str): Stock symbol
231
    
232
    Returns:
233
    dict: Analysis data including ratings, price targets, recommendations
234
    """
235

236
def get_financials(self, stock=None):
237
    """
238
    Get financial statements and key financial metrics.
239
    
240
    Parameters:
241
    - stock (str): Stock symbol
242
    
243
    Returns:
244
    dict: Financial data including income statement, balance sheet, cash flow
245
    """
246

247
def get_institutional_holding(self, stock=None, tId=None):
248
    """
249
    Get institutional ownership and holdings data.
250
    
251
    Parameters:
252
    - stock (str, optional): Stock symbol
253
    - tId (int, optional): Ticker ID
254
    
255
    Returns:
256
    dict: Institutional holdings with ownership percentages and changes
257
    """
258

259
def get_short_interest(self, stock=None, tId=None):
260
    """
261
    Get short interest data and statistics.
262
    
263
    Parameters:
264
    - stock (str, optional): Stock symbol
265
    - tId (int, optional): Ticker ID
266
    
267
    Returns:
268
    dict: Short interest data including short ratio, days to cover
269
    """
270
```
271

272
Usage examples:
273

274
```python
275
# Get analyst analysis
276
analysis = wb.get_analysis(stock='AAPL')
277
print(f"Rating: {analysis['rating']}")
278
print(f"Price Target: ${analysis['priceTarget']}")
279

280
# Get financial statements
281
financials = wb.get_financials(stock='AAPL')
282
print(f"Revenue: ${financials['revenue']}")
283

284
# Get institutional holdings
285
institutions = wb.get_institutional_holding(stock='AAPL')
286
for holding in institutions['data']:
287
    print(f"{holding['name']}: {holding['percentage']}%")
288
```
289

290
### Capital Flow & Market Data
291

292
Access advanced market data including capital flow and ETF holdings.
293

294
```python { .api }
295
def get_capital_flow(self, stock=None, tId=None, show_hist=True):
296
    """
297
    Get capital flow data showing money flow in/out of security.
298
    
299
    Parameters:
300
    - stock (str, optional): Stock symbol
301
    - tId (int, optional): Ticker ID
302
    - show_hist (bool): Include historical capital flow data
303
    
304
    Returns:
305
    dict: Capital flow data with inflow/outflow amounts and trends
306
    """
307

308
def get_etf_holding(self, stock=None, tId=None, has_num=0, count=50):
309
    """
310
    Get ETF holdings data for securities held by ETFs.
311
    
312
    Parameters:
313
    - stock (str, optional): Stock symbol
314
    - tId (int, optional): Ticker ID
315
    - has_num (int): Filter parameter for holdings data
316
    - count (int): Number of ETF holdings to retrieve
317
    
318
    Returns:
319
    dict: ETF holdings data showing which ETFs hold the security
320
    """
321

322
def get_five_min_ranking(self, extendTrading=0):
323
    """
324
    Get 5-minute ranking data for market movers.
325
    
326
    Parameters:
327
    - extendTrading (int): Include extended hours data
328
    
329
    Returns:
330
    dict: Ranking data for most active stocks in 5-minute intervals
331
    """
332
```
333

334
### Market Calendar & Events
335

336
Access earnings calendar and market events.
337

338
```python { .api }
339
def get_calendar(self, stock=None, tId=None):
340
    """
341
    Get earnings calendar and important dates for a security.
342
    
343
    Parameters:
344
    - stock (str, optional): Stock symbol
345
    - tId (int, optional): Ticker ID
346
    
347
    Returns:
348
    dict: Calendar events including earnings dates, dividends, splits
349
    """
350

351
def get_calendar_events(self, event, start_date=None, page=1, num=50):
352
    """
353
    Get market calendar events by type.
354
    
355
    Parameters:
356
    - event (str): Event type (e.g., 'earnings', 'dividends')
357
    - start_date (str, optional): Start date for events (YYYY-MM-DD)
358
    - page (int): Page number for pagination
359
    - num (int): Number of events per page
360
    
361
    Returns:
362
    list: List of calendar events
363
    """
364
```
365

366
Usage examples:
367

368
```python
369
# Get earnings calendar for Apple
370
calendar = wb.get_calendar(stock='AAPL')
371
print(f"Next earnings: {calendar['earningsDate']}")
372

373
# Get all earnings events for a date range
374
earnings = wb.get_calendar_events(
375
    event='earnings',
376
    start_date='2024-01-01',
377
    num=100
378
)
379
```
380

381
### Options Market Data
382

383
Get options-specific market data and pricing information.
384

385
```python { .api }
386
def get_options_bars(self, derivativeId=None, interval='1m', count=1, direction=1, timeStamp=None):
387
    """
388
    Get historical price bars for options contracts.
389
    
390
    Parameters:
391
    - derivativeId (int): Options contract derivative ID
392
    - interval (str): Time interval - '1m', '5m', '15m', '30m', '1h', '1d'
393
    - count (int): Number of bars to retrieve
394
    - direction (int): Direction flag (1 for ascending, -1 for descending)
395
    - timeStamp (int, optional): Start timestamp
396
    
397
    Returns:
398
    list: Options price bars with open, high, low, close, volume
399
    """
400
```
401

402
## Market Discovery & Screening
403

404
Find stocks and market opportunities using built-in screening tools.
405

406
```python { .api }
407
def active_gainer_loser(self, direction='gainer', rank_type='afterMarket', count=50):
408
    """
409
    Get list of active gainers or losers.
410
    
411
    Parameters:
412
    - direction (str): 'gainer', 'loser', or 'active'
413
    - rank_type (str): 'afterMarket', 'preMarket', or 'regular'
414
    - count (int): Number of results to return
415
    
416
    Returns:
417
    list: List of stocks with price change data
418
    """
419

420
def run_screener(self, region=None, price_lte=None, price_gte=None, pct_chg_gte=None, pct_chg_lte=None, sort=None, ...):
421
    """
422
    Run custom stock screener with filtering criteria.
423
    
424
    Parameters:
425
    - region (str, optional): Market region to screen
426
    - price_lte (float, optional): Maximum price filter
427
    - price_gte (float, optional): Minimum price filter
428
    - pct_chg_gte (float, optional): Minimum percentage change
429
    - pct_chg_lte (float, optional): Maximum percentage change
430
    - sort (str, optional): Sort criteria for results
431
    - ... (additional screening parameters)
432
    
433
    Returns:
434
    list: Filtered list of stocks matching criteria
435
    """
436
```
437

438
Usage examples:
439

440
```python
441
# Get top gainers
442
gainers = wb.active_gainer_loser(
443
    direction='gainer',
444
    rank_type='regular',
445
    count=20
446
)
447

448
# Screen for stocks under $50 with >5% gain
449
screen_results = wb.run_screener(
450
    price_lte=50.0,
451
    pct_chg_gte=5.0,
452
    sort='pct_chg_desc'
453
)
454
```
455

456
## Complete Market Data Example
457

458
```python
459
from webull import webull
460

461
wb = webull()
462
wb.login('your_email@example.com', 'your_password')
463

464
# Get comprehensive market data for a stock
465
symbol = 'AAPL'
466

467
try:
468
    # Basic quote and ticker info
469
    quote = wb.get_quote(stock=symbol)
470
    ticker_info = wb.get_ticker_info(stock=symbol)
471
    
472
    print(f"{ticker_info['name']} ({symbol})")
473
    print(f"Price: ${quote['close']} ({quote['changeRatio']}%)")
474
    print(f"Volume: {quote['volume']:,}")
475
    
476
    # Historical data
477
    daily_bars = wb.get_bars(stock=symbol, interval='d1', count=30)
478
    print(f"30-day high: ${max(bar['high'] for bar in daily_bars)}")
479
    print(f"30-day low: ${min(bar['low'] for bar in daily_bars)}")
480
    
481
    # News and analysis
482
    news = wb.get_news(stock=symbol, items=3)
483
    print(f"\nLatest news:")
484
    for article in news:
485
        print(f"- {article['title']}")
486
    
487
    # Financial analysis
488
    analysis = wb.get_analysis(stock=symbol)
489
    if analysis:
490
        print(f"\nAnalyst rating: {analysis.get('rating', 'N/A')}")
491
        print(f"Price target: ${analysis.get('priceTarget', 'N/A')}")
492
    
493
    # Institutional holdings
494
    institutions = wb.get_institutional_holding(stock=symbol)
495
    print(f"\nTop institutional holders:")
496
    for holding in institutions.get('data', [])[:3]:
497
        print(f"- {holding['name']}: {holding['percentage']}%")
498

499
except ValueError as e:
500
    print(f"Error getting market data: {e}")
501
```