yf-quotes 0.2.1

# yf-quotes

A Rust CLI tool for downloading historical OHLCV (Open, High, Low, Close, Volume) stock data from Yahoo Finance.

## Features

- 📈 Fetch historical stock data for any symbol
- 📊 Support for daily, weekly, and monthly intervals
- 🗓️ Flexible date ranges (predefined or custom)
- 📦 Output to JSON files (individual or combined)
- ⚡ Built-in rate limiting to avoid API throttling
- 🎯 Batch processing for multiple symbols
- ✨ Pretty-print JSON support

## Installation

### Build from source

```bash
cd tools/yf-quotes
cargo build --release
```

The binary will be available at `target/release/yf-quotes`.

### Add to PATH (optional)

```bash
# Copy to a directory in your PATH
sudo cp target/release/yf-quotes /usr/local/bin/
```

## Usage

### Basic Examples

```bash
# Fetch 1 year of daily data for Apple
yf-quotes AAPL --range 1y

# Fetch data for multiple symbols
yf-quotes AAPL MSFT GOOGL --range 1y

# Use custom date range
yf-quotes AAPL --start 2025-01-01 --end 2025-12-31

# Weekly data for 5 years
yf-quotes AAPL --interval weekly --range 5y

# Monthly data with pretty-printed JSON
yf-quotes AAPL --interval monthly --range 10y --pretty
```

### Combined Output

```bash
# Combine multiple symbols into a single file
yf-quotes AAPL MSFT GOOGL --range 1y --combine

# Combine with custom filename
yf-quotes AAPL MSFT GOOGL --range 1y --combine --combined-filename portfolio.json
```

### Advanced Options

```bash
# Custom output directory
yf-quotes AAPL --range 6mo --output-dir ./data/

# Adjust rate limiting (requests per minute)
yf-quotes AAPL MSFT GOOGL TSLA NVDA --range 1y --rate-limit 3

# Enable verbose logging
yf-quotes AAPL --range 1y --verbose
```

## CLI Arguments

| Argument | Short | Description | Default |
|----------|-------|-------------|---------|
| `<SYMBOLS>...` | | One or more stock symbols (required) | - |
| `--start` | `-s` | Start date in YYYY-MM-DD format | - |
| `--end` | `-e` | End date in YYYY-MM-DD format | Today |
| `--range` | `-r` | Predefined range: 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max | - |
| `--interval` | `-i` | Data interval: daily, weekly, monthly | daily |
| `--output-dir` | `-o` | Output directory for JSON files | `.` |
| `--combine` | | Combine all symbols into one file | false |
| `--combined-filename` | | Filename for combined output | combined.json |
| `--pretty` | | Pretty-print JSON output | false |
| `--rate-limit` | | Requests per minute | 5 |
| `--verbose` | `-v` | Enable verbose logging | false |

**Note:** Either `--range` or `--start` must be provided, but not both.

## Output Format

### Individual Symbol Output

Each symbol is saved to `<symbol>.json` (e.g., `aapl.json`):

```json
{
  "symbol": "AAPL",
  "currency": "USD",
  "exchange": "NMS",
  "interval": "daily",
  "start_date": "2025-01-01",
  "end_date": "2026-02-23",
  "fetched_at": "2026-02-23T14:30:00Z",
  "bars": [
    {
      "date": "2025-01-02",
      "timestamp": 1735776000,
      "open": 185.50,
      "high": 187.25,
      "low": 184.80,
      "close": 186.92,
      "adj_close": 186.92,
      "volume": 45678900
    },
    ...
  ]
}
```

### Combined Output

When using `--combine`, all symbols are saved to a single file:

```json
{
  "fetched_at": "2026-02-23T14:30:00Z",
  "interval": "daily",
  "symbols": [
    {
      "symbol": "AAPL",
      "currency": "USD",
      "exchange": "NMS",
      "interval": "daily",
      "start_date": "2025-01-01",
      "end_date": "2026-02-23",
      "fetched_at": "2026-02-23T14:30:00Z",
      "bars": [...]
    },
    {
      "symbol": "MSFT",
      ...
    }
  ]
}
```

## Predefined Date Ranges

| Range | Description |
|-------|-------------|
| `1mo` | 1 month |
| `3mo` | 3 months |
| `6mo` | 6 months |
| `1y` | 1 year |
| `2y` | 2 years |
| `5y` | 5 years |
| `10y` | 10 years |
| `ytd` | Year to date |
| `max` | Maximum available history |

## Data Intervals

| Interval | Description |
|----------|-------------|
| `daily` | Daily bars (default) |
| `weekly` | Weekly bars |
| `monthly` | Monthly bars |

## Error Handling

The tool handles various error conditions:

- **Invalid symbols**: Warns and continues with other symbols
- **Rate limiting**: Built-in rate limiter prevents 429 errors
- **No data available**: Skips symbols with no data
- **Network errors**: Reports and continues with remaining symbols

Failed symbols are reported in the summary at the end.

## Rate Limiting

Yahoo Finance has rate limits on API requests. The default is 5 requests per minute, which is conservative and should avoid rate limiting issues.

If you need to fetch many symbols, you can:
- Reduce the rate limit: `--rate-limit 3`
- Split into multiple batches
- Use the `--combine` flag to track progress better

## Examples

### Portfolio Tracking

```bash
# Track a portfolio of tech stocks
yf-quotes AAPL MSFT GOOGL AMZN META TSLA NVDA \
  --range 1y \
  --combine \
  --combined-filename tech_portfolio.json \
  --pretty
```

### Historical Analysis

```bash
# Get 10 years of monthly data for S&P 500
yf-quotes SPY --interval monthly --range 10y --pretty
```

### Comparison Study

```bash
# Compare multiple stocks over the same period
yf-quotes AAPL MSFT GOOGL \
  --start 2024-01-01 \
  --end 2024-12-31 \
  --output-dir ./comparison/
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This tool is for educational and research purposes only. Always verify data from official sources before making investment decisions.

Yahoo Finance data is provided by Yahoo Finance and subject to their terms of service.