0
# Quote Data Management
1

2
The Quote class provides access to historical and real-time price data including OHLC history, intraday trading data, and market depth information. It supports multiple Vietnamese and international data sources with automatic retry logic and caching.
3

4
## Capabilities
5

6
### Quote Class
7

8
Adapter for historical and intraday quote data with dynamic method dispatch based on the selected data source. Uses automatic parameter filtering and retry logic for reliable data access.
9

10
```python { .api }
11
class Quote:
12
    """
13
    Quote data adapter supporting multiple data sources.
14
    
15
    Supported sources: VCI, TCBS, MSN
16
    """
17
    
18
    def __init__(self, source: str = "vci", symbol: str = "", random_agent: bool = False, show_log: bool = False):
19
        """
20
        Initialize Quote data adapter.
21
        
22
        Args:
23
            source (str): Data source ("vci", "tcbs", "msn"), defaults to "vci"
24
            symbol (str): Default symbol for operations, defaults to ""
25
            random_agent (bool): Use random user agent, defaults to False
26
            show_log (bool): Enable logging, defaults to False
27
        """
28
```
29

30
### Historical Price Data
31

32
Retrieve historical OHLC (Open, High, Low, Close) price data for stocks, indices, forex, and cryptocurrencies with customizable date ranges and intervals.
33

34
```python { .api }
35
def history(self, *args, **kwargs) -> pd.DataFrame:
36
    """
37
    Load historical OHLC price data.
38
    
39
    Common parameters (vary by source):
40
        symbol (str): Security symbol
41
        start (str): Start date in "YYYY-MM-DD" format
42
        end (str): End date in "YYYY-MM-DD" format  
43
        interval (str): Data interval ("1D", "1W", "1M")
44
        
45
    Returns:
46
        pd.DataFrame: Historical price data with columns:
47
            - time/date: Timestamp
48
            - open: Opening price
49
            - high: High price
50
            - low: Low price
51
            - close: Closing price
52
            - volume: Trading volume
53
    """
54
```
55

56
#### Usage Examples
57

58
```python
59
from vnstock import Quote
60

61
# Initialize Quote adapter
62
quote = Quote(source="vci", symbol="TCB")
63

64
# Get 1 year of daily data
65
daily_data = quote.history(
66
    symbol="TCB",
67
    start="2023-01-01", 
68
    end="2023-12-31",
69
    interval="1D"
70
)
71

72
# Get weekly data
73
weekly_data = quote.history(
74
    symbol="VCB",
75
    start="2023-01-01",
76
    end="2023-12-31", 
77
    interval="1W"
78
)
79

80
# Using TCBS source
81
tcbs_quote = Quote(source="tcbs")
82
tcbs_data = tcbs_quote.history(
83
    symbol="HPG",
84
    start="2023-06-01",
85
    end="2023-12-31"
86
)
87
```
88

89
### Intraday Trading Data
90

91
Access intraday trading data including tick-by-tick transactions, minute-level price movements, and detailed trading activity.
92

93
```python { .api }
94
def intraday(self, *args, **kwargs) -> pd.DataFrame:
95
    """
96
    Load intraday trading data with high-frequency price and volume information.
97
    
98
    Common parameters (vary by source):
99
        symbol (str): Security symbol
100
        date (str): Trading date in "YYYY-MM-DD" format
101
        interval (str): Intraday interval ("1m", "5m", "15m", "30m", "1h")
102
        
103
    Returns:
104
        pd.DataFrame: Intraday trading data with columns:
105
            - time: Timestamp
106
            - open: Opening price
107
            - high: High price
108
            - low: Low price
109
            - close: Closing price
110
            - volume: Trading volume
111
            - value: Trading value
112
    """
113
```
114

115
#### Usage Examples
116

117
```python
118
# Get intraday minute data for today
119
intraday_data = quote.intraday(
120
    symbol="TCB",
121
    date="2023-12-15",
122
    interval="1m"
123
)
124

125
# Get 5-minute intervals
126
intraday_5m = quote.intraday(
127
    symbol="VCB", 
128
    date="2023-12-15",
129
    interval="5m"
130
)
131

132
# Hourly intraday data
133
hourly_data = quote.intraday(
134
    symbol="HPG",
135
    date="2023-12-15",
136
    interval="1h"
137
)
138
```
139

140
### Market Depth Data
141

142
Retrieve price depth information including order book data, bid/ask levels, and market liquidity indicators.
143

144
```python { .api }
145
def price_depth(self, *args, **kwargs) -> pd.DataFrame:
146
    """
147
    Load price depth (order book) data showing bid/ask levels and quantities.
148
    
149
    Common parameters (vary by source):
150
        symbol (str): Security symbol  
151
        levels (int): Number of price levels to retrieve
152
        
153
    Returns:
154
        pd.DataFrame: Order book data with columns:
155
            - bid_price_1, bid_price_2, ...: Bid prices by level
156
            - bid_volume_1, bid_volume_2, ...: Bid quantities by level
157
            - ask_price_1, ask_price_2, ...: Ask prices by level  
158
            - ask_volume_1, ask_volume_2, ...: Ask quantities by level
159
            - timestamp: Data timestamp
160
    """
161
```
162

163
#### Usage Examples
164

165
```python
166
# Get order book for TCB stock
167
order_book = quote.price_depth(symbol="TCB", levels=5)
168

169
# Get market depth with more levels
170
deep_book = quote.price_depth(symbol="VCB", levels=10)
171

172
# Current bid/ask spread analysis
173
spread_data = quote.price_depth(symbol="HPG")
174
```
175

176
## Data Source Specifics
177

178
### VCI (Vietnam Capital Securities)
179

180
- **Coverage**: Vietnamese stocks, ETFs, covered warrants
181
- **Historical Data**: Up to 10+ years of daily data
182
- **Intraday Data**: Real-time tick data and minute intervals
183
- **Market Depth**: 5-10 levels of order book data
184
- **Update Frequency**: Real-time during market hours
185

186
#### VCI-Specific Parameters
187

188
```python
189
# VCI history parameters
190
history(
191
    symbol="TCB",
192
    start="2023-01-01",
193
    end="2023-12-31",
194
    resolution="1D",  # VCI uses "resolution" instead of "interval"
195
    type="stock"      # "stock", "index", "warrant"
196
)
197

198
# VCI intraday parameters  
199
intraday(
200
    symbol="TCB",
201
    fromDate="2023-12-15 09:00:00",
202
    toDate="2023-12-15 15:00:00",
203
    resolution="1"  # Minutes
204
)
205
```
206

207
### TCBS (Techcombank Securities)
208

209
- **Coverage**: Vietnamese stocks, indices, derivatives
210
- **Historical Data**: Comprehensive historical database
211
- **Intraday Data**: Minute-level and tick data
212
- **Market Depth**: Real-time order book
213
- **Update Frequency**: Real-time during market hours
214

215
#### TCBS-Specific Parameters
216

217
```python
218
# TCBS history parameters
219
history(
220
    ticker="HPG",
221
    type="stock",
222
    start="2023-01-01",
223
    end="2023-12-31",
224
    period="D"  # Daily period
225
)
226

227
# TCBS intraday
228
intraday(
229
    ticker="VCB",
230
    date="2023-12-15",
231
    size=1000  # Number of records
232
)
233
```
234

235
### MSN (Microsoft Network)
236

237
- **Coverage**: Global stocks, forex, crypto, indices
238
- **Historical Data**: Long-term historical data for global markets
239
- **Intraday Data**: International market data
240
- **Market Depth**: Limited order book for major markets
241
- **Update Frequency**: Real-time for major markets
242

243
#### MSN-Specific Parameters
244

245
```python
246
# MSN forex data
247
history(
248
    symbol="USDVND",
249
    start="2023-01-01",
250
    end="2023-12-31",
251
    interval="1D"
252
)
253

254
# MSN crypto data
255
history(
256
    symbol="BTC", 
257
    range="1Y",  # MSN supports range parameter
258
    interval="1D"
259
)
260
```
261

262
## Error Handling
263

264
The Quote class includes built-in error handling and retry logic:
265

266
- **Network Errors**: Automatic retry with exponential backoff
267
- **Rate Limiting**: Handles API rate limits with appropriate delays
268
- **Data Validation**: Validates date ranges and symbol formats
269
- **Source Fallback**: Can switch between data sources if primary fails
270

271
#### Common Error Scenarios
272

273
```python
274
try:
275
    data = quote.history(symbol="INVALID", start="2023-01-01", end="2023-12-31")
276
except ValueError as e:
277
    print(f"Invalid symbol or date range: {e}")
278
except ConnectionError as e:
279
    print(f"Network error: {e}")
280
except Exception as e:
281
    print(f"Unexpected error: {e}")
282
```
283

284
## Performance Considerations
285

286
- **Caching**: Recent data requests are cached to improve performance
287
- **Batch Requests**: Use date ranges instead of multiple single-day requests
288
- **Data Sources**: VCI and TCBS are optimized for Vietnamese markets
289
- **Rate Limits**: Respect API rate limits to avoid throttling
290
- **Memory Usage**: Large date ranges may consume significant memory