examples.py

#!/usr/bin/env python3
"""
Zillow Scraper API - Quick Start Examples
Powered by RealtyAPI.io

These examples demonstrate how to use the Zillow Scraper API
to extract real estate data from Zillow programmatically.

Get your API key at: https://www.realtyapi.io
"""

import json
from zillow_api import ZillowAPI

# ─────────────────────────────────────────────
# Replace with your API key from https://www.realtyapi.io
# ─────────────────────────────────────────────
API_KEY = "YOUR_API_KEY_HERE"

api = ZillowAPI(API_KEY)


def example_property_by_address():
    """Example: Get property details by address."""
    print("\n=== Property Lookup by Address ===")
    data = api.get_property_by_address("1875 AVONDALE Circle, Jacksonville, FL 32205")
    print(json.dumps(data, indent=2))


def example_property_by_zpid():
    """Example: Get property details by ZPID."""
    print("\n=== Property Lookup by ZPID ===")
    data = api.get_property_by_zpid("44471319")
    print(json.dumps(data, indent=2))


def example_property_by_url():
    """Example: Get property details by Zillow URL."""
    print("\n=== Property Lookup by Zillow URL ===")
    data = api.get_property_by_url(
        "https://www.zillow.com/homedetails/2762-Downing-St-Jacksonville-FL-32205/44471319_zpid/"
    )
    print(json.dumps(data, indent=2))


def example_search_for_sale():
    """Example: Search homes for sale in New York."""
    print("\n=== Search Homes For Sale ===")
    data = api.search_by_address(
        location="New York, NY",
        listing_status="For_Sale",
        sort_order="Newest",
        bed_min="2",
        bathrooms="OnePlus",
        list_price_range="min:500000, max:2000000",
        page=1,
    )
    print(json.dumps(data, indent=2))


def example_search_rentals():
    """Example: Search rentals in Los Angeles."""
    print("\n=== Search Rentals ===")
    data = api.search_by_address(
        location="Los Angeles, CA",
        listing_status="For_Rent",
        sort_order="Price_Low_to_High",
        bed_min="1",
        home_type="Apartments/Condos/Co-ops",
        page=1,
    )
    print(json.dumps(data, indent=2))


def example_search_sold():
    """Example: Search recently sold homes."""
    print("\n=== Recently Sold Homes ===")
    data = api.search_by_address(
        location="Miami, FL",
        listing_status="Sold",
        sold_in_last="30_days",
        sort_order="Newest",
        page=1,
    )
    print(json.dumps(data, indent=2))


def example_search_multi_location():
    """Example: Search multiple locations at once (up to 5)."""
    print("\n=== Multi-Location Search ===")
    data = api.search_by_address(
        location="New York, NY; Seattle, WA; Austin, TX",
        listing_status="For_Sale",
        page=1,
    )
    print(json.dumps(data, indent=2))


def example_search_by_coordinates():
    """Example: Search by coordinates (circle search)."""
    print("\n=== Search by Coordinates ===")
    data = api.search_by_coordinates(
        latitude="40.599283",
        longitude="-74.129194",
        radius="0.5",
        listing_status="For_Sale",
    )
    print(json.dumps(data, indent=2))


def example_comparable_homes():
    """Example: Get comparable homes for a property."""
    print("\n=== Comparable Homes ===")
    data = api.get_comparable_homes(
        byaddress="1221 Victoria St APT 301, Honolulu, HI 96814"
    )
    print(json.dumps(data, indent=2))


def example_price_history():
    """Example: Get price history for a property."""
    print("\n=== Price History ===")
    data = api.get_price_history(byzpid="44471319")
    print(json.dumps(data, indent=2))


def example_walk_score():
    """Example: Get walk, transit, and bike scores."""
    print("\n=== Walk/Transit/Bike Scores ===")
    data = api.get_walk_transit_bike_scores(
        byaddress="1875 AVONDALE Circle, Jacksonville, FL 32205"
    )
    print(json.dumps(data, indent=2))


def example_zestimate_history():
    """Example: Get 10-year Zestimate history."""
    print("\n=== Zestimate History (10 years) ===")
    data = api.get_zestimate_history(
        byaddress="1875 AVONDALE Circle, Jacksonville, FL 32205",
        recent_first="True",
    )
    print(json.dumps(data, indent=2))


def example_housing_market():
    """Example: Get housing market analytics for a city."""
    print("\n=== Housing Market Analytics ===")
    data = api.get_housing_market(
        search_query="Austin, TX",
        home_type="All_Homes",
        exclude_rental_trends=False,
    )
    print(json.dumps(data, indent=2))


def example_agent_search():
    """Example: Search for real estate agents."""
    print("\n=== Agent Search ===")
    data = api.search_agents(
        location="Saint Louis, MO",
        is_top_agent=True,
        specialties="luxury-homes",
    )
    print(json.dumps(data, indent=2))


def example_agent_details():
    """Example: Get agent profile details."""
    print("\n=== Agent Details ===")
    data = api.get_agent_details(username="Alex-Antigua")
    print(json.dumps(data, indent=2))


def example_skip_trace():
    """Example: Skip trace a property address."""
    print("\n=== Skip Tracing ===")
    print("Note: This costs 10 API requests per call")
    data = api.skip_trace_by_address(
        street="3828 Double Oak Ln",
        citystatezip="Irving, TX 75061",
    )
    print(json.dumps(data, indent=2))


def example_property_images():
    """Example: Get property images."""
    print("\n=== Property Images ===")
    data = api.get_property_images(
        byaddress="1875 AVONDALE Circle, Jacksonville, FL 32205"
    )
    print(json.dumps(data, indent=2))


# ─────────────────────────────────────────────
# Run examples (uncomment the ones you want)
# ─────────────────────────────────────────────
if __name__ == "__main__":
    # Property Data
    example_property_by_address()
    # example_property_by_zpid()
    # example_property_by_url()
    # example_property_images()
    # example_price_history()
    # example_comparable_homes()
    # example_walk_score()
    # example_zestimate_history()

    # Search
    # example_search_for_sale()
    # example_search_rentals()
    # example_search_sold()
    # example_search_multi_location()
    # example_search_by_coordinates()

    # Market & Agents
    # example_housing_market()
    # example_agent_search()
    # example_agent_details()

    # Skip Tracing
    # example_skip_trace()