rentcache/docs/USAGE.md

# Usage Guide

This comprehensive guide covers how to use RentCache effectively, from basic operations to advanced configuration and optimization strategies.

## 🚀 Getting Started

### Basic Workflow

1. **Start the server**
2. **Create API keys** for your applications  
3. **Make API calls** through RentCache instead of directly to Rentcast
4. **Monitor performance** and costs
5. **Optimize cache settings** based on usage patterns

## 🖥️ Server Management

### Starting the Server

```bash
# Development mode (with auto-reload)
uv run rentcache server --reload --log-level DEBUG

# Production mode
uv run rentcache server --host 0.0.0.0 --port 8000

# Custom configuration
uv run rentcache server \
  --host 0.0.0.0 \
  --port 8080 \
  --log-level INFO

# Using uvicorn directly
uv run uvicorn rentcache.server:app --reload --port 8000
```

### Server Options

| Option | Description | Default |
|--------|-------------|---------|
| `--host` | Bind address | `0.0.0.0` |
| `--port` | Port number | `8000` |
| `--reload` | Auto-reload on code changes | `false` |
| `--log-level` | Logging level | `info` |

### Stopping the Server

```bash
# Graceful shutdown (Ctrl+C or)
kill -TERM <pid>

# Force shutdown
kill -KILL <pid>

# Using systemd
sudo systemctl stop rentcache
```

## 🔑 API Key Management

### Creating API Keys

```bash
# Basic API key creation
uv run rentcache create-key my_app YOUR_RENTCAST_API_KEY

# With custom limits and expiration
uv run rentcache create-key production_app YOUR_RENTCAST_API_KEY \
  --daily-limit 5000 \
  --monthly-limit 100000 \
  --expires 2024-12-31

# Development key with higher limits
uv run rentcache create-key dev_app YOUR_RENTCAST_API_KEY \
  --daily-limit 10000 \
  --monthly-limit 200000
```

### Listing API Keys

```bash
# View all API keys with usage stats
uv run rentcache list-keys
```

Example output:
```
┌─────────────────┬──────────┬─────────────┬───────────────┬────────────┬─────────────┐
│ Name            │ Status   │ Daily Usage │ Monthly Usage │ Created    │ Expires     │
├─────────────────┼──────────┼─────────────┼───────────────┼────────────┼─────────────┤
│ production_app  │ 🟢 Active │ 150/5000    │ 3200/100000   │ 2024-01-01 │ 2024-12-31  │
│ dev_app         │ 🟢 Active │ 45/10000    │ 890/200000    │ 2024-01-05 │ Never       │
│ test_app        │ 🔴 Inactive │ 0/1000     │ 0/10000       │ 2024-01-10 │ Never       │
└─────────────────┴──────────┴─────────────┴───────────────┴────────────┴─────────────┘
```

### Updating API Keys

```bash
# Update limits
uv run rentcache update-key production_app --daily-limit 10000

# Activate/deactivate key
uv run rentcache update-key test_app --active
uv run rentcache update-key test_app --inactive

# Update multiple settings
uv run rentcache update-key production_app \
  --daily-limit 7500 \
  --monthly-limit 150000 \
  --active
```

### Deleting API Keys

```bash
# Delete with confirmation prompt
uv run rentcache delete-key old_app

# The command will prompt for confirmation:
# Are you sure you want to delete this API key? [y/N]: y
```

## 🌐 Making API Calls

### Basic Request Structure

Replace `api.rentcast.io` with your RentCache server URL and add your API key to the Authorization header:

```bash
# Direct to Rentcast (what you were doing before)
curl -H "X-Api-Key: YOUR_RENTCAST_KEY" \
  "https://api.rentcast.io/v1/properties?city=Austin&state=TX"

# Through RentCache (what you should do now)
curl -H "Authorization: Bearer YOUR_RENTCAST_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX"
```

### Property Data Endpoints

#### Search Properties

```bash
# Basic property search
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&limit=10"

# Advanced property search
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?address=123%20Main%20St&zipCode=78701&propertyType=Single%20Family&bedrooms=3&bathrooms=2&squareFootage=1500"

# With pagination
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&offset=20&limit=20"
```

#### Get Property by ID

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties/12345"
```

### Value and Rent Estimates

#### Property Value Estimates

```bash
# Get value estimate
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/value?address=123%20Main%20St&city=Austin&state=TX"

# Value estimate with property details
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/value?zipCode=78701&propertyType=Single%20Family&bedrooms=3&bathrooms=2&squareFootage=1800"
```

#### Rent Estimates

```bash
# Get rent estimate
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/rent?address=123%20Main%20St&city=Austin&state=TX"

# Rent estimate with property details
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/rent?zipCode=78701&bedrooms=2&bathrooms=2&propertyType=Condo"
```

### Listings Data

#### Sale Listings

```bash
# Search for sale listings
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/sale?city=Austin&state=TX&bedrooms=3&limit=10"

# Sale listings with price range (if supported by Rentcast)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/sale?zipCode=78701&minPrice=300000&maxPrice=600000"
```

#### Rental Listings

```bash
# Search rental listings
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/rental?city=Austin&state=TX&bedrooms=2&limit=15"

# Rental listings with filters
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/rental?zipCode=78701&propertyType=Apartment&bathrooms=2"
```

### Market Statistics

```bash
# Get market statistics
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/markets/stats?zipCode=78701"

# Market stats by city/state
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/markets/stats?city=Austin&state=TX"
```

### Comparable Properties

```bash
# Get comparable properties
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/comparables?address=123%20Main%20St&city=Austin&state=TX"

# Comparables with property details
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/comparables?zipCode=78701&bedrooms=3&bathrooms=2&squareFootage=1800&propertyType=Single%20Family"
```

## ⚡ Cache Control

### Understanding Cache Behavior

RentCache uses intelligent caching with different TTL (Time To Live) values based on data volatility:

- **Property Records**: 24 hours (expensive, relatively stable)
- **Value/Rent Estimates**: 1 hour (expensive, moderately dynamic)  
- **Listings**: 30 minutes (frequently updated)
- **Market Stats**: 2 hours (aggregated data, slower to change)

### Cache Control Parameters

#### Force Refresh

Force a fresh API call even if cached data exists:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&force_refresh=true"
```

#### Override TTL

Set custom cache duration (in seconds):

```bash
# Cache for 2 hours (7200 seconds)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/value?address=123%20Main%20St&ttl_override=7200"

# Cache for 10 minutes (600 seconds)  
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/sale?city=Austin&ttl_override=600"
```

### Reading Response Headers

Every response includes cache information:

```bash
curl -I -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX"

# Response headers include:
# X-Cache-Hit: true
# X-Response-Time-MS: 12.5
# X-Estimated-Cost: 0.0  (cache hits cost nothing!)
```

### Cache Management CLI

```bash
# View cache statistics
uv run rentcache stats

# Clear specific endpoint cache
uv run rentcache clear-cache --endpoint properties

# Clear cache older than 24 hours
uv run rentcache clear-cache --older-than 24

# Clear all cache (use with caution!)
uv run rentcache clear-cache
```

## 📊 Monitoring and Analytics

### Usage Statistics

```bash
# Overall statistics
uv run rentcache stats

# Statistics for specific endpoint
uv run rentcache stats --endpoint properties

# Statistics for specific time period
uv run rentcache stats --days 30
```

Example output:
```
┌─────────────────────┬──────────┐
│ Metric              │ Value    │
├─────────────────────┼──────────┤
│ Total Requests      │ 2,543    │
│ Cache Hits          │ 2,287    │
│ Cache Misses        │ 256      │
│ Hit Ratio           │ 89.92%   │
│ Avg Response Time   │ 28.5ms   │
│ Total Cost          │ $512.00  │
│ Cache Entries       │ 1,234    │
└─────────────────────┴──────────┘

📊 Top Endpoints:
┌─────────────────────┬───────────┐
│ Endpoint            │ Requests  │
├─────────────────────┼───────────┤
│ properties          │ 1,205     │
│ value_estimate      │ 892       │
│ listings_sale       │ 234       │
│ rent_estimate       │ 156       │
│ market_stats        │ 56        │
└─────────────────────┴───────────┘
```

### Health Monitoring

```bash
# Check system health
uv run rentcache health

# Expected output when healthy:
# ✅ Database: Connected
# 🔑 Active API Keys: 3
# 💾 Valid Cache Entries: 1234
# 📈 Requests (24h): 456
# 
# 🎉 System is healthy!
```

### Real-time Metrics via HTTP

```bash
# Get detailed system metrics
curl http://localhost:8000/metrics | jq '.'

# Key metrics to monitor:
curl http://localhost:8000/metrics | jq '{
  cache_hit_ratio: .cache_hit_ratio,
  avg_response_time: .avg_response_time_ms,
  requests_24h: .requests_24h,
  cost_24h: .cost_24h
}'
```

## 💰 Cost Management

### Understanding Costs

RentCache tracks estimated costs for different endpoint types:

| Endpoint Type | Estimated Cost | Cache TTL | Typical Savings |
|---------------|----------------|-----------|-----------------|
| Property Records | $1.00 | 24 hours | 90% |
| Value Estimates | $2.00 | 1 hour | 85% |
| Rent Estimates | $2.00 | 1 hour | 85% |
| Market Stats | $5.00 | 2 hours | 95% |
| Listings | $0.50 | 30 minutes | 70% |
| Comparables | $3.00 | 1 hour | 88% |

### Monitoring Costs

```bash
# View cost breakdown
uv run rentcache stats | grep -A 5 "Cost"

# Daily cost tracking
curl http://localhost:8000/metrics | jq '.cost_24h'

# Calculate savings
curl http://localhost:8000/metrics | jq '
  .total_requests as $total |
  .cache_hits as $hits |
  ($hits / $total * 100) as $hit_ratio |
  "Cache Hit Ratio: \($hit_ratio)%"
'
```

### Cost Optimization Strategies

1. **Increase Cache TTL for Stable Data**:
   ```bash
   # Cache property records for 48 hours instead of 24
   curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8000/api/v1/properties?address=123%20Main%20St&ttl_override=172800"
   ```

2. **Batch Related Requests**:
   ```bash
   # Instead of multiple individual requests, search broader then filter locally
   curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8000/api/v1/properties?zipCode=78701&limit=100"
   ```

3. **Use Appropriate Endpoints**:
   ```bash
   # Use less expensive listing searches when you don't need full property records
   curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8000/api/v1/listings/sale?city=Austin&state=TX"
   ```

## 🔧 Advanced Configuration

### Environment-Based Configuration

Create different configuration files for different environments:

#### Development (`.env.dev`)
```env
DEBUG=true
LOG_LEVEL=DEBUG
DATABASE_URL=sqlite+aiosqlite:///./dev_rentcache.db
DEFAULT_CACHE_TTL=1800  # 30 minutes for faster testing
CORS_ORIGINS=http://localhost:3000,http://localhost:8080
```

#### Staging (`.env.staging`)
```env
DEBUG=false
LOG_LEVEL=INFO
DATABASE_URL=postgresql://user:pass@staging-db:5432/rentcache
REDIS_ENABLED=true
REDIS_URL=redis://staging-redis:6379
DEFAULT_CACHE_TTL=3600
```

#### Production (`.env.prod`)
```env
DEBUG=false
LOG_LEVEL=WARNING
DATABASE_URL=postgresql://user:pass@prod-db:5432/rentcache
REDIS_ENABLED=true
REDIS_URL=redis://prod-redis:6379
DEFAULT_CACHE_TTL=7200
EXPENSIVE_ENDPOINTS_TTL=172800
```

### Rate Limiting Configuration

#### Global Rate Limits

```env
# Requests per API key per time period
GLOBAL_RATE_LIMIT=2000/hour
DAILY_RATE_LIMIT=10000/day
```

#### Per-Endpoint Rate Limits

```env
# Expensive endpoints get lower limits
VALUE_ESTIMATE_RATE_LIMIT=30/minute
RENT_ESTIMATE_RATE_LIMIT=30/minute
MARKET_STATS_RATE_LIMIT=20/minute

# Cheaper endpoints can have higher limits
LISTINGS_RATE_LIMIT=100/minute
PROPERTIES_RATE_LIMIT=60/minute
```

### Custom Cache Strategies

#### Endpoint-Specific TTL Configuration

```python
# Example: Custom cache configuration
CUSTOM_CACHE_TTL = {
    "properties": 86400,      # 24 hours
    "value_estimate": 3600,   # 1 hour  
    "rent_estimate": 3600,    # 1 hour
    "listings_sale": 1800,    # 30 minutes
    "listings_rental": 1800,  # 30 minutes
    "market_stats": 7200,     # 2 hours
    "comparables": 3600       # 1 hour
}
```

## 🐛 Troubleshooting

### Common Issues and Solutions

#### Cache Miss Rate Too High

**Problem**: Low cache hit ratio (< 60%)

**Solutions**:
1. Check if `force_refresh=true` is being used too often
2. Verify TTL settings aren't too short
3. Check if requests have slight parameter variations

```bash
# Analyze request patterns
uv run rentcache stats --endpoint properties | grep "Total Requests"

# Check for parameter variations
curl http://localhost:8000/metrics | jq '.top_endpoints'
```

#### High Response Times

**Problem**: Slow API responses

**Solutions**:
1. Enable Redis for faster cache access
2. Check database performance
3. Monitor upstream Rentcast API performance

```bash
# Check average response times
curl http://localhost:8000/metrics | jq '.avg_response_time_ms'

# Monitor cache hit ratio
uv run rentcache stats | grep "Hit Ratio"
```

#### Rate Limit Exceeded

**Problem**: Getting 429 errors

**Solutions**:
1. Check current usage against limits
2. Increase limits if needed
3. Implement request queuing in your application

```bash
# Check current usage
uv run rentcache list-keys

# Update limits
uv run rentcache update-key my_app --daily-limit 10000
```

#### Database Errors

**Problem**: Database connection or performance issues

**Solutions**:
1. Check database connectivity
2. Monitor database size and performance
3. Consider migrating from SQLite to PostgreSQL

```bash
# Check database health
uv run rentcache health

# Check database size
du -h rentcache.db

# Clear old cache entries
uv run rentcache clear-cache --older-than 168  # 7 days
```

### Debug Mode

Enable detailed logging for troubleshooting:

```bash
# Start server with debug logging
uv run rentcache server --log-level DEBUG

# Check logs for specific requests
tail -f /var/log/rentcache.log | grep "ERROR\|WARNING"
```

### Performance Monitoring

```bash
# Monitor request patterns
watch -n 5 'curl -s http://localhost:8000/metrics | jq "{requests_24h, cache_hits_24h, hit_ratio: (.cache_hits_24h / .requests_24h * 100)}"'

# Monitor system resources
htop

# Monitor database performance
# SQLite: Use .timer on in sqlite3 CLI
# PostgreSQL: Use pg_stat_statements extension
```

## 🔄 Best Practices

### Request Optimization

1. **Consistent Parameter Formatting**: Keep parameter formats consistent to maximize cache hits
2. **Appropriate Pagination**: Don't request more data than needed
3. **Smart Caching**: Use longer TTLs for stable data like property records
4. **Batch Operations**: Group related requests when possible

### Cache Strategy

1. **Monitor Hit Ratios**: Aim for 80%+ cache hit ratios
2. **Adjust TTLs**: Balance freshness vs. cost savings
3. **Regular Cleanup**: Clean old cache entries periodically
4. **Use Redis**: Enable Redis for high-traffic applications

### Security

1. **Rotate API Keys**: Regularly rotate Rentcast API keys
2. **Monitor Usage**: Watch for unusual usage patterns
3. **Set Appropriate Limits**: Don't set limits too high
4. **Use HTTPS**: Always use HTTPS in production

### Monitoring

1. **Set Up Alerts**: Alert on high error rates or low cache hit ratios  
2. **Regular Health Checks**: Monitor the `/health` endpoint
3. **Cost Tracking**: Monitor daily/monthly costs
4. **Performance Metrics**: Track response times and throughput

---

Ready to optimize your Rentcast API usage? Check out the [API Reference](API.md) for detailed endpoint documentation or the [Installation Guide](INSTALLATION.md) for setup instructions.