Skip to content

README.md

Latest commit

 

History

History
211 lines (170 loc) · 5.75 KB

README.md

File metadata and controls

211 lines (170 loc) · 5.75 KB

avm_api - Property Valuation Service

A REST API service that provides property valuations and detailed property information using Attom Data's real estate APIs.

🏠 Overview

This service combines Attom Data's AVM (Automated Valuation Model) and Basic Property Profile APIs to provide comprehensive property reports. It offers both machine-readable raw data and homeowner-friendly formatted responses.

✨ Features

  • Interactive D3.js Charts: Professional property assessment visualizations
  • Comprehensive Analysis: Basic + AVM + Timeline + Auto-Charts in one call
  • Assessment History: 14+ years of property tax and valuation trends
  • Combined Reports: AVM valuation with basic profile fallback
  • Multiple Report Types: AVM-only, basic profile-only, or comprehensive
  • Batch Processing: Handle up to 10 addresses simultaneously
  • Developer Library: JavaScript library for easy chart embedding
  • Auto-Browser Launch: Seamless chart opening with URL parameters
  • Raw Data Access: Full API responses for advanced use cases
  • REST API: 17 HTTP endpoints with JSON responses

🚀 Quick Start

Prerequisites

  • Python 3.7+
  • Attom Data API key
  • Required packages: requests, flask, flask-cors, python-dotenv

Installation

  1. Set up environment variables: Create a .env file in the AVM_Api/ directory:

    cd AVM_Api
echo "ATTOM_API_KEY=your_api_key_here" > .env

  2. Install dependencies:

    pip install -r requirements.txt

  3. Start the API server:

    cd AVM_Api
python property_rest_api.py

The API will be available at: http://localhost:5000

📡 API Endpoints

Health Check

curl http://localhost:5000/health

Property Reports

Combined Report (Recommended)

Gets AVM data if available, falls back to basic profile:

curl -X POST http://localhost:5000/property/combined \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St, Boston, MA 02101"}'

AVM Report Only

curl -X POST http://localhost:5000/property/avm \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St, Boston, MA 02101"}'

Basic Profile Only

curl -X POST http://localhost:5000/property/basic \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St, Boston, MA 02101"}'

Batch Processing

Process up to 10 addresses at once:

curl -X POST http://localhost:5000/property/batch \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "123 Main St, Boston, MA 02101",
      "456 Oak Ave, Springfield, IL 62701"
    ],
    "report_type": "combined"
  }'

📊 Response Format

Successful AVM Response

{
  "address": "123 MAIN ST, BOSTON, MA 02101",
  "current_estimated_value": "$1,445,419",
  "value_range_low": "$1,373,148", 
  "value_range_high": "$1,517,689",
  "confidence_score": "95/100",
  "estimate_date": "2024-08-25",
  "property_size": "3,054 sqft",
  "year_built": "1994",
  "bedrooms": "3",
  "bathrooms": "3",
  "lot_size": "0.25 acres",
  "last_sale_price": "$370,000",
  "last_sale_date": "2000-05-15",
  "current_assessment": "$1,200,000",
  "owner": "John Smith",
  "data_retrieved": "2024-08-25 15:30:00"
}

Basic Profile Fallback

{
  "address": "208 ASHMONT ST, DORCHESTER CENTER, MA 02124",
  "property_size": "N/A",
  "year_built": "N/A", 
  "bedrooms": "N/A",
  "bathrooms": "N/A",
  "lot_size": "N/A",
  "property_type": "N/A",
  "property_subtype": "N/A",
  "last_sale_price": "N/A",
  "last_sale_date": "N/A",
  "current_assessment": "N/A",
  "owner": "N/A",
  "valuation_note": "No current market valuation available - showing basic property data only",
  "data_retrieved": "2024-08-25 15:30:00"
}

🗂️ File Structure

AVM_Api/
├── property_api_service.py    # Core service logic
├── property_rest_api.py       # Flask REST API wrapper  
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables (API key)
├── API_USAGE_GUIDE.md        # Detailed usage examples
└── README.md                 # This file

🛠️ Development

Running Interactively

python property_api_service.py

This starts an interactive command-line interface for testing the service directly.

Available Methods

  • get_combined_report(address) - Combined AVM + basic profile
  • get_property_report(address) - AVM report only
  • get_basic_profile_report(address) - Basic profile only
  • get_avm_history(address) - Raw AVM data
  • get_basic_profile(address) - Raw basic profile data

🔒 Production Considerations

Security

  • Use HTTPS in production
  • Implement API key authentication
  • Add rate limiting
  • Enable request logging

Performance

  • Cache successful responses (24 hours recommended)
  • Implement connection pooling
  • Add request timeouts
  • Monitor API quota usage

Error Handling

  • Always check for "error" field in responses
  • Implement retry logic for 5xx errors
  • Handle network timeouts gracefully
  • Log errors for debugging

📚 Documentation

📊 Interactive Charts

Access professional D3.js visualizations at http://localhost:5000/charts

Features:

  • 14+ years of assessment history trends
  • Interactive tooltips and responsive design
  • Auto-population with address parameters
  • Developer JavaScript library available

🔗 Dependencies

  • Attom Data API: Real estate data provider
  • Flask: Web framework for REST API
  • Flask-CORS: Cross-origin resource sharing
  • requests: HTTP client library
  • python-dotenv: Environment variable management

📄 License

This project integrates with Attom Data's commercial APIs. Ensure you have appropriate licensing and API access before use.