rentcache/docs/API.md

API Reference

Complete reference documentation for all RentCache API endpoints, including Rentcast proxy endpoints and system management endpoints.

📋 Overview

RentCache provides two types of endpoints:

1. Proxy Endpoints (/api/v1/*) - Mirror Rentcast API endpoints with intelligent caching
2. System Endpoints - Health checks, metrics, and administration

All endpoints support JSON responses and include cache performance headers.

🔐 Authentication

All API endpoints require Bearer token authentication using your Rentcast API key:

Authorization: Bearer YOUR_RENTCAST_API_KEY

Example:

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

📊 Common Response Headers

All responses include performance and cache information:

Header	Description	Example
X-Cache-Hit	Whether response was served from cache	true or false
X-Response-Time-MS	Total response time in milliseconds	45.2
X-Estimated-Cost	Estimated Rentcast API cost (cache misses only)	2.0

🏠 Property Endpoints

Search Properties

Search for property records using various criteria.

Endpoint: GET /api/v1/properties
Cache TTL: 24 hours
Estimated Cost: $1.00 per request
Rate Limit: 60/minute

Parameters

Parameter	Type	Required	Description
address	string	No	Full or partial address
zipCode	string	No	ZIP/postal code
city	string	No	City name
state	string	No	State abbreviation (e.g., "TX")
propertyType	string	No	Property type filter
bedrooms	integer	No	Number of bedrooms
bathrooms	number	No	Number of bathrooms (supports decimals)
squareFootage	integer	No	Square footage
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Results per page (default: 100, max: 500)
force_refresh	boolean	No	Force cache refresh (default: false)
ttl_override	integer	No	Override cache TTL in seconds

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&propertyType=Single%20Family&bedrooms=3&limit=10"

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "12345",
      "address": "123 Main St",
      "city": "Austin", 
      "state": "TX",
      "zipCode": "78701",
      "propertyType": "Single Family",
      "bedrooms": 3,
      "bathrooms": 2,
      "squareFootage": 1800,
      "lotSize": 0.25,
      "yearBuilt": 1995,
      "lastSalePrice": 450000,
      "lastSaleDate": "2023-06-15",
      "estimatedValue": 485000,
      "latitude": 30.2672,
      "longitude": -97.7431
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}

Get Property by ID

Retrieve detailed information for a specific property.

Endpoint: GET /api/v1/properties/{property_id}
Cache TTL: 24 hours
Estimated Cost: $1.00 per request
Rate Limit: 60/minute

Parameters

Parameter	Type	Required	Description
property_id	string	Yes	Unique property identifier
force_refresh	boolean	No	Force cache refresh
ttl_override	integer	No	Override cache TTL in seconds

Example Request

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

Example Response

{
  "status": "success",
  "data": {
    "id": "12345",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701",
    "propertyType": "Single Family",
    "bedrooms": 3,
    "bathrooms": 2,
    "squareFootage": 1800,
    "lotSize": 0.25,
    "yearBuilt": 1995,
    "assessedValue": 475000,
    "marketValue": 485000,
    "propertyHistory": [
      {
        "date": "2023-06-15",
        "price": 450000,
        "type": "sale"
      }
    ],
    "neighborhood": {
      "name": "Downtown Austin",
      "walkScore": 85,
      "crimeScore": "Low"
    }
  }
}

💰 Value Estimation Endpoints

Get Property Value Estimate

Get an estimated market value for a property.

Endpoint: GET /api/v1/estimates/value
Cache TTL: 1 hour
Estimated Cost: $2.00 per request
Rate Limit: 30/minute

Parameters

Parameter	Type	Required	Description
address	string	No	Property address
zipCode	string	No	ZIP code
city	string	No	City name
state	string	No	State abbreviation
propertyType	string	No	Property type
bedrooms	integer	No	Number of bedrooms
bathrooms	number	No	Number of bathrooms
squareFootage	integer	No	Square footage
force_refresh	boolean	No	Force cache refresh
ttl_override	integer	No	Override cache TTL

Example Request

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

Example Response

{
  "status": "success",
  "data": {
    "address": "123 Main St, Austin, TX 78701",
    "estimatedValue": 485000,
    "confidence": 85,
    "valuationRange": {
      "low": 460000,
      "high": 510000
    },
    "comparables": [
      {
        "address": "125 Main St",
        "salePrice": 475000,
        "saleDate": "2023-08-12",
        "distance": 0.1
      }
    ],
    "marketTrends": {
      "monthlyChange": 2.1,
      "yearlyChange": 8.5
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Bulk Value Estimates

Get value estimates for multiple properties in a single request.

Endpoint: POST /api/v1/estimates/value/bulk
Cache TTL: 1 hour
Estimated Cost: $10.00 per request
Rate Limit: 10/minute

Request Body

{
  "properties": [
    {
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX"
    },
    {
      "address": "456 Oak Ave", 
      "city": "Austin",
      "state": "TX"
    }
  ],
  "force_refresh": false,
  "ttl_override": 7200
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      {"address": "123 Main St", "city": "Austin", "state": "TX"},
      {"address": "456 Oak Ave", "city": "Austin", "state": "TX"}
    ]
  }' \
  "http://localhost:8000/api/v1/estimates/value/bulk"

🏠 Rent Estimation Endpoints

Get Rent Estimate

Get an estimated rental value for a property.

Endpoint: GET /api/v1/estimates/rent
Cache TTL: 1 hour
Estimated Cost: $2.00 per request
Rate Limit: 30/minute

Parameters

Same as value estimation endpoint.

Example Request

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

Example Response

{
  "status": "success",
  "data": {
    "address": "123 Main St, Austin, TX 78701",
    "estimatedRent": 2450,
    "confidence": 82,
    "rentRange": {
      "low": 2200,
      "high": 2700
    },
    "comparables": [
      {
        "address": "125 Main St",
        "rent": 2400,
        "bedrooms": 3,
        "bathrooms": 2,
        "distance": 0.1
      }
    ],
    "marketMetrics": {
      "averageRent": 2380,
      "rentPerSqFt": 1.36,
      "occupancyRate": 94.2
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Bulk Rent Estimates

Get rent estimates for multiple properties.

Endpoint: POST /api/v1/estimates/rent/bulk
Cache TTL: 1 hour
Estimated Cost: $10.00 per request
Rate Limit: 10/minute

Similar to bulk value estimates but returns rental estimates.

🏘️ Listings Endpoints

Search Sale Listings

Search for properties currently for sale.

Endpoint: GET /api/v1/listings/sale
Cache TTL: 30 minutes
Estimated Cost: $0.50 per request
Rate Limit: 60/minute

Parameters

Parameter	Type	Required	Description
address	string	No	Address filter
zipCode	string	No	ZIP code filter
city	string	No	City filter
state	string	No	State filter
propertyType	string	No	Property type filter
bedrooms	integer	No	Bedroom count filter
bathrooms	number	No	Bathroom count filter
minPrice	integer	No	Minimum listing price
maxPrice	integer	No	Maximum listing price
offset	integer	No	Pagination offset
limit	integer	No	Results per page

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/sale?city=Austin&state=TX&bedrooms=3&minPrice=300000&maxPrice=600000"

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "listing_123",
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "price": 485000,
      "bedrooms": 3,
      "bathrooms": 2,
      "squareFootage": 1800,
      "lotSize": 0.25,
      "propertyType": "Single Family",
      "listingDate": "2024-01-10",
      "daysOnMarket": 5,
      "status": "Active",
      "mls": "12345678",
      "photos": [
        "https://example.com/photo1.jpg"
      ],
      "description": "Beautiful home in downtown Austin..."
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}

Search Rental Listings

Search for rental properties.

Endpoint: GET /api/v1/listings/rental
Cache TTL: 30 minutes
Estimated Cost: $0.50 per request
Rate Limit: 60/minute

Parameters

Similar to sale listings, but with minRent/maxRent instead of price filters.

Example Response

{
  "status": "success", 
  "data": [
    {
      "id": "rental_456",
      "address": "456 Oak Ave",
      "city": "Austin",
      "state": "TX",
      "rent": 2400,
      "bedrooms": 2,
      "bathrooms": 2,
      "squareFootage": 1200,
      "propertyType": "Apartment",
      "availableDate": "2024-02-01",
      "leaseTerms": "12 months",
      "petPolicy": "Cats allowed",
      "amenities": ["Pool", "Gym", "Parking"],
      "photos": ["https://example.com/rental1.jpg"]
    }
  ]
}

Get Listing by ID

Get detailed information for a specific listing.

Endpoint: GET /api/v1/listings/{listing_id}
Cache TTL: 1 hour
Estimated Cost: $0.50 per request
Rate Limit: 60/minute

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/listing_123"

📈 Market Data Endpoints

Market Statistics

Get comprehensive market statistics for an area.

Endpoint: GET /api/v1/markets/stats
Cache TTL: 2 hours
Estimated Cost: $5.00 per request
Rate Limit: 20/minute

Parameters

Parameter	Type	Required	Description
zipCode	string	No	ZIP code for market area
city	string	No	City name
state	string	No	State abbreviation
force_refresh	boolean	No	Force cache refresh
ttl_override	integer	No	Override cache TTL

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/markets/stats?zipCode=78701"

Example Response

{
  "status": "success",
  "data": {
    "location": {
      "zipCode": "78701",
      "city": "Austin",
      "state": "TX"
    },
    "salesMetrics": {
      "medianSalePrice": 485000,
      "averageSalePrice": 512000,
      "totalSales": 156,
      "daysOnMarket": 28,
      "pricePerSqFt": 275,
      "monthlyChange": 2.1,
      "yearlyChange": 8.5
    },
    "rentalMetrics": {
      "medianRent": 2400,
      "averageRent": 2450,
      "totalRentals": 89,
      "vacancyRate": 5.8,
      "rentPerSqFt": 1.36,
      "monthlyChange": 1.2,
      "yearlyChange": 12.3
    },
    "marketTrends": {
      "inventoryLevel": "Low",
      "marketTempo": "Fast",
      "buyerDemand": "High",
      "priceDirection": "Rising"
    },
    "demographics": {
      "medianHouseholdIncome": 65000,
      "population": 15420,
      "medianAge": 32
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Comparable Properties

Find comparable properties for analysis.

Endpoint: GET /api/v1/comparables
Cache TTL: 1 hour
Estimated Cost: $3.00 per request
Rate Limit: 30/minute

Parameters

Parameter	Type	Required	Description
address	string	No	Subject property address
zipCode	string	No	ZIP code
city	string	No	City name
state	string	No	State abbreviation
propertyType	string	No	Property type
bedrooms	integer	No	Number of bedrooms
bathrooms	number	No	Number of bathrooms
squareFootage	integer	No	Square footage
radius	number	No	Search radius in miles (default: 1.0)
maxComps	integer	No	Maximum comparables to return (default: 10)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/comparables?address=123%20Main%20St&city=Austin&state=TX&radius=0.5"

Example Response

{
  "status": "success",
  "data": {
    "subjectProperty": {
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX"
    },
    "comparables": [
      {
        "address": "125 Main St",
        "salePrice": 475000,
        "saleDate": "2023-08-12",
        "bedrooms": 3,
        "bathrooms": 2,
        "squareFootage": 1750,
        "lotSize": 0.22,
        "yearBuilt": 1992,
        "distance": 0.1,
        "similarity": 95,
        "adjustments": {
          "location": 0,
          "size": 5000,
          "age": -2000,
          "condition": 0
        },
        "adjustedPrice": 478000
      }
    ],
    "summary": {
      "averagePrice": 478000,
      "priceRange": {
        "low": 460000,
        "high": 495000
      },
      "averagePricePerSqFt": 268,
      "confidenceScore": 88
    }
  }
}

🛠️ System Endpoints

Health Check

Check system health and status.

Endpoint: GET /health
Authentication: None required
Rate Limit: None

Example Request

curl http://localhost:8000/health

Example Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "database": "healthy",
  "cache_backend": "sqlite",
  "active_keys": 3,
  "total_cache_entries": 1234,
  "cache_hit_ratio_24h": 0.89
}

System Metrics

Get detailed system performance metrics.

Endpoint: GET /metrics
Authentication: None required
Rate Limit: 10/minute

Example Request

curl http://localhost:8000/metrics

Example Response

{
  "total_requests": 2543,
  "cache_hits": 2287,
  "cache_misses": 256,
  "cache_hit_ratio": 0.8992,
  "active_api_keys": 3,
  "total_cost_saved": 4574.0,
  "avg_response_time_ms": 28.5,
  "uptime_seconds": 86400,
  "requests_24h": 456,
  "cache_hits_24h": 405,
  "cost_24h": 102.0,
  "top_endpoints": [
    {
      "endpoint": "properties",
      "requests": 1205
    },
    {
      "endpoint": "value_estimate", 
      "requests": 892
    },
    {
      "endpoint": "listings_sale",
      "requests": 234
    }
  ]
}

🔧 Administration Endpoints

Create API Key

Create a new API key for application access.

Endpoint: POST /admin/api-keys
Authentication: Admin required (implementation-specific)
Rate Limit: 5/minute

Request Body

{
  "key_name": "production_app",
  "rentcast_api_key": "sk_live_1234567890abcdef",
  "daily_limit": 5000,
  "monthly_limit": 100000,
  "expires_at": "2024-12-31T23:59:59Z"
}

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "my_app",
    "rentcast_api_key": "sk_live_1234567890abcdef",
    "daily_limit": 1000,
    "monthly_limit": 10000
  }' \
  "http://localhost:8000/admin/api-keys"

Example Response

{
  "id": 1,
  "key_name": "my_app",
  "daily_limit": 1000,
  "monthly_limit": 10000,
  "daily_usage": 0,
  "monthly_usage": 0,
  "is_active": true,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Clear Cache

Clear cache entries based on criteria.

Endpoint: POST /admin/cache/clear
Authentication: Admin required
Rate Limit: 5/minute

Request Body

{
  "endpoint": "properties",
  "older_than_hours": 24,
  "invalid_only": false
}

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "properties",
    "older_than_hours": 24
  }' \
  "http://localhost:8000/admin/cache/clear"

Example Response

{
  "message": "Cleared 156 cache entries",
  "pattern": "*properties*"
}

🚫 Error Responses

All endpoints return consistent error responses:

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
502	Bad Gateway	Upstream API error
503	Service Unavailable	Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily API limit of 1000 requests exceeded",
    "details": {
      "daily_usage": 1001,
      "daily_limit": 1000,
      "reset_time": "2024-01-16T00:00:00Z"
    }
  }
}

Common Error Codes

Code	Description
INVALID_API_KEY	API key not found or inactive
RATE_LIMIT_EXCEEDED	Request rate limit exceeded
INVALID_PARAMETERS	Request parameters validation failed
UPSTREAM_API_ERROR	Error from Rentcast API
CACHE_ERROR	Cache system error
DATABASE_ERROR	Database connection error

📊 Response Caching

Cache Headers

All responses include cache-related headers:

X-Cache-Hit: true
X-Response-Time-MS: 12.5
X-Cache-Age: 3600
X-Cache-TTL: 86400

Cache Key Generation

Cache keys are generated using MD5 hash of:

• HTTP method
• Endpoint name
• Sorted query parameters
• Request body (for POST requests)

Example: GET:properties:{"city":"Austin","state":"TX"} → a1b2c3d4e5f6...

Cache Invalidation

Cache entries can be invalidated:

• Automatically when TTL expires
• Manually via admin endpoints
• Using force_refresh=true parameter
• Through CLI commands

🔄 Rate Limiting

Rate Limit Headers

Rate-limited endpoints include headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642248000
X-RateLimit-Window: 60

Rate Limit Tiers

Endpoint Type	Rate Limit	Burst Allowance
Property Search	60/minute	10 requests
Value Estimates	30/minute	5 requests
Market Stats	20/minute	3 requests
Listings	60/minute	10 requests
Bulk Operations	10/minute	2 requests

Rate Limit Bypass

Cache hits do not count against rate limits, providing natural rate limit relief through caching.

---

📚 Additional Resources

• Installation Guide - Setup and configuration
• Usage Guide - Comprehensive usage examples
• Rentcast API Documentation - Official API docs

For questions or issues, please refer to the project repository at git.supported.systems/MCP/rentcache.