Home Repair Cost API

A comprehensive FastAPI application that provides home repair cost estimates with regional adjustments, similar to Homewyse.com. This standalone microservice offers accurate cost calculations across 50+ repair types with California regional multipliers.

Features

• ✅ 50+ Repair Types across Electrical, Plumbing, HVAC, Roofing, Structural, and more
• ✅ Regional Cost Adjustments for California zip codes with accurate multipliers
• ✅ API Key Authentication with secure key generation and validation
• ✅ Rate Limiting to prevent abuse (1000 requests/hour per key)
• ✅ Batch Processing for multiple repair estimates at once
• ✅ Docker Ready with multi-stage builds and production optimization
• ✅ Comprehensive Documentation with OpenAPI/Swagger integration
• ✅ Health Monitoring with built-in health check endpoints

Quick Start

Using Docker (Recommended)

# Development setup
docker-compose -f docker-compose.dev.yml up --build

# Production setup
docker-compose -f docker-compose.prod.yml up -d

The API will be available at:

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/api/v1/health
• ReDoc Documentation: http://localhost:8000/redoc

Local Development

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API Usage

1. Create API Key

curl -X POST "http://localhost:8000/api/v1/auth/create-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Application"}'

Response:

{
  "api_key": "rca_abc123...",
  "name": "My Application",
  "created_at": "2024-01-15T10:30:00Z",
  "rate_limit": 1000
}

2. Get Single Repair Estimate

curl -X GET "http://localhost:8000/api/v1/repair-cost/electrical_panel_replacement?zip_code=90210&scope=average" \
  -H "X-API-Key: rca_your-api-key-here"

3. Get Batch Estimates

curl -X POST "http://localhost:8000/api/v1/repair-cost/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rca_your-api-key-here" \
  -d '{
    "repairs": ["electrical_panel_replacement", "water_heater_replacement"],
    "zip_code": "90210",
    "scope": "average"
  }'

4. List Available Repair Types

curl -X GET "http://localhost:8000/api/v1/repair-types" \
  -H "X-API-Key: rca_your-api-key-here"

Response Format

{
  "repair_type": "electrical_panel_replacement",
  "location": {
    "zip_code": "90210",
    "region": "Beverly Hills, CA",
    "cost_multiplier": 1.45
  },
  "cost_estimate": {
    "low": 1740,
    "average": 3045,
    "high": 4350,
    "national_base": 2100
  },
  "details": {
    "labor_hours": "6-8",
    "materials_cost_percent": 40,
    "permit_required": true,
    "urgency_level": "critical",
    "description": "Replace main electrical panel and upgrade to current code"
  },
  "factors": {
    "regional_labor_cost": "Very High",
    "material_availability": "Good",
    "permit_complexity": "High"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Supported Repair Categories

Category	Examples	Count
Electrical	Panel replacement, outlet installation, rewiring	6 types
Plumbing	Pipe repairs, toilet replacement, water heater	7 types
HVAC	Furnace replacement, AC repair, duct cleaning	6 types
Roofing	Leak repair, shingle replacement, gutter repair	6 types
Structural	Foundation repair, window replacement, deck repair	6 types
Flooring	Hardwood repair, tile replacement, carpet	4 types
Appliances	Dishwasher, refrigerator, washer/dryer repair	3 types
Exterior	Siding, fence, driveway, garage door repair	4 types
Safety	Smoke detectors, security systems	2 types
Other	Insulation, painting, weatherproofing	6 types

Regional Coverage

Currently supports California with specific multipliers for:

• High Cost Areas: San Francisco (1.50x), Beverly Hills (1.45x), Palo Alto (1.45x)
• Moderate Cost Areas: Santa Barbara (1.25x), Riverside (1.20x), San Jose (1.35x)
• Default California: 1.25x multiplier for unlisted zip codes

Deployment Options

1. Local Docker Development

docker-compose -f docker-compose.dev.yml up --build

2. Production Docker

# Set environment variables
export API_KEY_SECRET="your-production-secret"

# Deploy
docker-compose -f docker-compose.prod.yml up -d

3. Cloud Deployment (Railway/Render)

# Build and push
docker build -t repair-cost-api .
docker push your-registry/repair-cost-api:latest

# Deploy with environment variables:
# DATABASE_URL, API_KEY_SECRET, ENVIRONMENT=production

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite:///./data/repair_costs.db	Database connection string
API_KEY_SECRET	dev-secret	Secret for API key generation
ENVIRONMENT	development	Environment mode
LOG_LEVEL	debug	Logging level
WORKERS	1	Number of worker processes

Project Structure

repair-cost-api/
├── app/
│   ├── main.py              # FastAPI application
│   ├── models/              # Database and Pydantic models
│   │   ├── repair.py        # Repair SQLAlchemy model
│   │   ├── auth.py          # API key model
│   │   └── schemas.py       # Pydantic schemas
│   ├── routers/             # API endpoints
│   │   ├── repairs.py       # Repair cost endpoints
│   │   ├── auth.py          # Authentication endpoints
│   │   └── health.py        # Health check
│   ├── services/            # Business logic
│   │   ├── cost_calculator.py
│   │   └── auth_service.py
│   ├── database/            # Database setup
│   │   ├── connection.py
│   │   └── seed_data.py     # 50+ repair types
│   └── utils/
│       └── regional.py      # Regional multipliers
├── data/                    # SQLite database
├── logs/                    # Application logs
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.dev.yml  # Development setup
├── docker-compose.prod.yml # Production setup
└── requirements.txt        # Python dependencies

API Integration Example

# How your main application can use this API
import requests

class RepairCostClient:
    def __init__(self, api_key: str, base_url: str = "http://localhost:8000"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {"X-API-Key": api_key}
    
    def get_repair_cost(self, repair_type: str, zip_code: str, scope: str = "average"):
        response = requests.get(
            f"{self.base_url}/api/v1/repair-cost/{repair_type}",
            params={"zip_code": zip_code, "scope": scope},
            headers=self.headers
        )
        return response.json()
    
    def get_batch_costs(self, repairs: list, zip_code: str, scope: str = "average"):
        response = requests.post(
            f"{self.base_url}/api/v1/repair-cost/batch",
            json={"repairs": repairs, "zip_code": zip_code, "scope": scope},
            headers=self.headers
        )
        return response.json()

# Usage
client = RepairCostClient("rca_your-api-key")
cost = client.get_repair_cost("electrical_panel_replacement", "90210")
print(f"Average cost: ${cost['cost_estimate']['average']}")

Security Features

• API Key Authentication: Secure key-based access control
• Rate Limiting: Prevents API abuse with configurable limits
• Input Validation: Comprehensive validation of all inputs
• Non-root Container: Security best practices in Docker
• Environment Isolation: Separate development and production configs

Monitoring & Health

• Health Endpoint: /api/v1/health for monitoring systems
• Database Health: Automatic database connection testing
• Container Health: Built-in Docker health checks
• Structured Logging: JSON logs for production monitoring

Support

This API is designed to be consumed by AI chat applications and property inspection tools. For integration support or feature requests, refer to the OpenAPI documentation at /docs.

License

Built for property inspection and home repair cost estimation use cases.