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

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

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

Value and Rent Estimates

Property Value Estimates

# 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

# 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

# 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

# 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

# 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

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

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

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

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

# 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

# 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

# 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

# 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

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

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

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

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

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)

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)

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

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

Per-Endpoint Rate Limits

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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 for detailed endpoint documentation or the Installation Guide for setup instructions.