rentcache/docs/QUICKSTART.md

# Quick Start Guide

Get RentCache running in 5 minutes and start saving on Rentcast API costs immediately.

## ⚡ 5-Minute Setup

### Prerequisites

- **Docker & Docker Compose**: [Install Docker](https://docs.docker.com/get-docker/)
- **Rentcast API Key**: [Get your key](https://developers.rentcast.io/)
- **Domain** (optional): For production deployment

### Step 1: Clone and Configure

```bash
# Clone repository
git clone https://git.supported.systems/MCP/rentcache.git
cd rentcache

# Quick setup with defaults
make setup
```

### Step 2: Create API Key

```bash
# Replace 'your_rentcast_api_key' with your actual Rentcast API key
make create-key NAME=quickstart KEY=your_rentcast_api_key
```

### Step 3: Test Your Setup

```bash
# Test with a simple property search
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Austin&state=TX&limit=1"
```

**🎉 That's it!** RentCache is now proxying your Rentcast API calls with intelligent caching.

## 🔍 Verify Everything Works

### Check System Health

```bash
curl https://rentcache.l.supported.systems/health
```

**Expected Response:**
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "database": "healthy",
  "cache_backend": "sqlite",
  "active_keys": 1,
  "total_cache_entries": 0,
  "cache_hit_ratio_24h": null
}
```

### View API Documentation

Open in browser: **https://rentcache.l.supported.systems/docs**

### Monitor Performance

```bash
# View real-time metrics
curl https://rentcache.l.supported.systems/metrics | jq
```

## 🚀 First API Calls

### Property Search

```bash
# Search properties in Austin, TX
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Austin&state=TX&limit=5"
```

### Value Estimate

```bash
# Get property value estimate
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/estimates/value?address=123%20Main%20St&city=Austin&state=TX"
```

### Rent Estimate

```bash
# Get rent estimate
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/estimates/rent?address=123%20Main%20St&city=Austin&state=TX"
```

### Market Statistics

```bash
# Get market stats for ZIP code
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/markets/stats?zipCode=78701"
```

## 💰 See Your Savings

### Make the Same Call Twice

```bash
# First call (cache miss - costs money)
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Dallas&state=TX&limit=1"

# Second call (cache hit - FREE!)
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Dallas&state=TX&limit=1"
```

### Check Response Headers

```bash
# Look for cache hit indicators
curl -I -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Dallas&state=TX&limit=1"
```

**Response Headers:**
```
X-Cache-Hit: true
X-Response-Time-MS: 12.5
# X-Estimated-Cost header only appears on cache misses
```

### View Usage Statistics

```bash
# Check your savings so far
curl https://rentcache.l.supported.systems/metrics | jq '{
  total_requests: .total_requests,
  cache_hits: .cache_hits,
  cache_hit_ratio: .cache_hit_ratio,
  estimated_savings: "Calculated from cache hits"
}'
```

## 🔧 Common Use Cases

### Real Estate Applications

#### Property Portfolio Analysis
```bash
# Get multiple properties in a neighborhood
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?zipCode=78701&limit=50"

# Get value estimates for each (subsequent calls will be cached)
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/estimates/value?zipCode=78701&propertyType=Single%20Family"
```

#### Market Research
```bash
# Research multiple markets efficiently
for city in Austin Dallas Houston; do
  curl -H "Authorization: Bearer your_rentcast_api_key" \
    "https://rentcache.l.supported.systems/api/v1/markets/stats?city=$city&state=TX"
done
```

#### Rental Property Management
```bash
# Monitor rental market for your properties
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/listings/rental?city=Austin&state=TX&bedrooms=3&limit=20"

# Get rent estimates for comparison
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/estimates/rent?address=123%20Property%20St&city=Austin&state=TX"
```

### Investment Analysis

#### Comparative Market Analysis
```bash
# Get comparable properties
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/comparables?address=456%20Investment%20Ave&city=Austin&state=TX"

# Analyze multiple similar properties (cached for efficiency)
for address in "123 Main St" "456 Oak Ave" "789 Pine St"; do
  curl -H "Authorization: Bearer your_rentcast_api_key" \
    "https://rentcache.l.supported.systems/api/v1/estimates/value?address=$address&city=Austin&state=TX"
done
```

## 🎛️ Cache Control

### Force Fresh Data

When you need the absolute latest data:

```bash
# Force refresh (bypasses cache)
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/estimates/value?address=123%20Main%20St&city=Austin&state=TX&force_refresh=true"
```

### Custom Cache Duration

Set custom cache times for your specific needs:

```bash
# Cache for 2 hours (7200 seconds)
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/properties?city=Austin&state=TX&ttl_override=7200"

# Cache for 10 minutes (600 seconds) for frequently changing data
curl -H "Authorization: Bearer your_rentcast_api_key" \
  "https://rentcache.l.supported.systems/api/v1/listings/rental?city=Austin&state=TX&ttl_override=600"
```

## 📊 Monitoring Your Usage

### Real-Time Dashboard

Access your usage dashboard:
**https://rentcache.l.supported.systems/docs**

### CLI Monitoring

```bash
# View usage statistics
make stats

# Check system health
make health

# View recent logs
make logs
```

### Key Metrics to Watch

1. **Cache Hit Ratio**: Aim for >80%
   ```bash
   curl -s https://rentcache.l.supported.systems/metrics | jq '.cache_hit_ratio'
   ```

2. **Response Times**: Should be <50ms for cache hits
   ```bash
   curl -s https://rentcache.l.supported.systems/metrics | jq '.avg_response_time_ms'
   ```

3. **Cost Savings**: Track your monthly savings
   ```bash
   curl -s https://rentcache.l.supported.systems/metrics | jq '.cost_24h'
   ```

## 🛠️ Troubleshooting

### Common Issues

#### "401 Unauthorized" Error
```bash
# Check if your API key is created and active
make list-keys

# Recreate if needed
make create-key NAME=quickstart KEY=your_correct_rentcast_key
```

#### "Service Unavailable" Error
```bash
# Check system health
curl https://rentcache.l.supported.systems/health

# Check logs
make logs
```

#### Slow Response Times
```bash
# Check if Redis is enabled for better cache performance
make dev  # Includes Redis profile
```

### Getting Help

1. **Check Logs**: `make logs`
2. **Verify Health**: `curl https://rentcache.l.supported.systems/health`
3. **Test API Key**: `make list-keys`
4. **View Documentation**: https://rentcache.l.supported.systems/docs

## 🎯 Next Steps

### Optimize for Your Workload

1. **Adjust Cache TTLs**: Based on your data freshness needs
2. **Monitor Usage Patterns**: Use the metrics endpoint
3. **Set Up Alerts**: Monitor cache hit ratios and costs
4. **Scale Resources**: Add Redis for high-traffic applications

### Integration Examples

#### Python Application
```python
import httpx

class RentCacheClient:
    def __init__(self, api_key: str, base_url: str = "https://rentcache.l.supported.systems"):
        self.api_key = api_key
        self.base_url = base_url
        self.client = httpx.AsyncClient()
    
    async def search_properties(self, city: str, state: str, limit: int = 10):
        headers = {"Authorization": f"Bearer {self.api_key}"}
        params = {"city": city, "state": state, "limit": limit}
        
        response = await self.client.get(
            f"{self.base_url}/api/v1/properties",
            headers=headers,
            params=params
        )
        return response.json()

# Usage
client = RentCacheClient("your_rentcast_api_key")
properties = await client.search_properties("Austin", "TX")
```

#### Node.js Application
```javascript
const axios = require('axios');

class RentCacheClient {
    constructor(apiKey, baseUrl = 'https://rentcache.l.supported.systems') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
        this.client = axios.create({
            baseURL: baseUrl,
            headers: {
                'Authorization': `Bearer ${apiKey}`
            }
        });
    }
    
    async searchProperties(city, state, limit = 10) {
        const response = await this.client.get('/api/v1/properties', {
            params: { city, state, limit }
        });
        return response.data;
    }
}

// Usage
const client = new RentCacheClient('your_rentcast_api_key');
const properties = await client.searchProperties('Austin', 'TX');
```

### Advanced Configuration

#### Custom Deployment
```bash
# Clone for custom configuration
git clone https://git.supported.systems/MCP/rentcache.git
cd rentcache

# Edit configuration
cp .env.example .env
nano .env  # Customize settings

# Deploy with custom config
make setup
```

#### Production Deployment
See the [Deployment Guide](DEPLOYMENT.md) for:
- PostgreSQL database setup
- Redis configuration
- SSL certificate management
- Monitoring and alerting
- Backup strategies

---

**🎉 Congratulations!** You're now using RentCache to reduce your Rentcast API costs. Monitor your cache hit ratio and enjoy the savings!

**Need help?** Check the [Usage Guide](USAGE.md) for detailed examples or the [API Reference](API.md) for complete endpoint documentation.