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
• Rentcast API Key: Get your key
• Domain (optional): For production deployment

Step 1: Clone and Configure

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

# Quick setup with defaults
make setup

Step 2: Create API Key

# 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

# 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

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

Expected Response:

{
  "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

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

🚀 First API Calls

Property Search

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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

# 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%

   curl -s https://rentcache.l.supported.systems/metrics | jq '.cache_hit_ratio'
   

2. Response Times: Should be <50ms for cache hits

   curl -s https://rentcache.l.supported.systems/metrics | jq '.avg_response_time_ms'
   

3. Cost Savings: Track your monthly savings

   curl -s https://rentcache.l.supported.systems/metrics | jq '.cost_24h'
   

🛠️ Troubleshooting

Common Issues

"401 Unauthorized" Error

# 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

# Check system health
curl https://rentcache.l.supported.systems/health

# Check logs
make logs

Slow Response Times

# 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

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

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

# 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 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 for detailed examples or the API Reference for complete endpoint documentation.