Properties API¶

def get_properties(
    top: Optional[int] = None,
    skip: Optional[int] = None,
    filter_query: Optional[str] = None,
    select: Optional[List[str]] = None,
    orderby: Optional[str] = None,
    count: bool = False
) -> Dict[str, Any]

from wfrmls import WFRMLSClient

client = WFRMLSClient()

# Basic usage - get first 10 active properties
response = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'",
    top=10
)
properties = response["value"]

# Advanced filtering with field selection
luxury_response = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        "ListPrice ge 750000 and "
        "BedroomsTotal ge 4"
    ),
    select=["ListingId", "ListPrice", "City", "BedroomsTotal"],
    orderby="ListPrice desc",
    top=25
)

# Pagination using @odata.nextLink
first_page = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'",
    top=50
)

# If there's a next page
if "@odata.nextLink" in first_page:
    # Extract skip value from nextLink for next page
    # The nextLink contains the full URL with skip parameter
    pass

# Count total results
result_with_count = client.property.get_properties(
    filter_query="City eq 'Salt Lake City'",
    count=True,
    top=10
)
total_properties = result_with_count.get("@odata.count", 0)

def get_property(listing_id: str) -> Dict[str, Any]

property_detail = client.property.get_property("1611952")
parcel_number = property_detail["ParcelNumber"]

# Get specific property
property_detail = client.property.get_property("1611952")

print(f"Parcel: {property_detail['ParcelNumber']}")
print(f"Address: {property_detail['UnparsedAddress']}")
print(f"Price: ${property_detail['ListPrice']:,}")
print(f"Bedrooms: {property_detail.get('BedroomsTotal', 'N/A')}")

# Active properties
active_properties = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'"
)

# Properties in specific city
salt_lake_properties = client.property.get_properties(
    filter_query="City eq 'Salt Lake City' and StandardStatus eq 'Active'"
)

# Price range search
mid_range_homes = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        "ListPrice ge 300000 and "
        "ListPrice le 600000"
    )
)

# Family homes with specific criteria
family_homes = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        "PropertyType eq 'Residential' and "
        "BedroomsTotal ge 3 and "
        "BathroomsTotalInteger ge 2 and "
        "SquareFeet ge 2000"
    ),
    select=[
        "ListingId", "Address", "ListPrice", "BedroomsTotal",
        "BathroomsTotalInteger", "SquareFeet"
    ],
    orderby="ListPrice asc"
)

# Recently updated properties
from datetime import datetime, timedelta

week_ago = (datetime.now() - timedelta(days=7)).isoformat()
recent_updates = client.property.get_properties(
    filter_query=f"ModificationTimestamp ge {week_ago}",
    orderby="ModificationTimestamp desc"
)

# Properties with price reductions
price_drops = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        "ListPrice lt OriginalListPrice"
    ),
    select=[
        "ListingId", "Address", "ListPrice", "OriginalListPrice",
        "PriceChangeTimestamp"
    ],
    orderby="PriceChangeTimestamp desc"
)

# Properties with coordinates
properties_with_coords = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        "Latitude ne null and "
        "Longitude ne null"
    ),
    select=["ListingId", "Address", "ListPrice", "Latitude", "Longitude"]
)

# Properties in specific ZIP codes
target_zips = ['84101', '84102', '84103']
zip_filter = " or ".join([f"PostalCode eq '{zip}'" for zip in target_zips])

zip_properties = client.property.get_properties(
    filter_query=f"StandardStatus eq 'Active' and ({zip_filter})"
)

# Approximate proximity search (simplified)
downtown_lat, downtown_lon = 40.7589, -111.8883
tolerance = 0.01  # Roughly 0.7 miles

near_downtown = client.property.get_properties(
    filter_query=(
        "StandardStatus eq 'Active' and "
        f"abs(Latitude sub {downtown_lat}) le {tolerance} and "
        f"abs(Longitude sub {downtown_lon}) le {tolerance}"
    )
)

# Properties by specific agent
agent_listings = client.property.get_properties(
    filter_query="ListAgentKey eq 'AGT123456' and StandardStatus eq 'Active'",
    select=[
        "ListingId", "Address", "ListPrice", "DaysOnMarket",
        "ListAgentFullName"
    ]
)

# Properties by office
office_listings = client.property.get_properties(
    filter_query="ListOfficeKey eq 'OFF789' and StandardStatus eq 'Active'",
    select=[
        "ListingId", "Address", "ListPrice", "ListAgentFullName",
        "ListOfficeName"
    ]
)

def paginate_properties(page_size=100):
    """Manually paginate through all active properties."""

    all_properties = []
    skip = 0

    while True:
        batch = client.property.get_properties(
            filter_query="StandardStatus eq 'Active'",
            top=page_size,
            skip=skip,
            orderby="ListingId asc"  # Consistent ordering
        )

        if not batch:
            break

        all_properties.extend(batch)
        skip += page_size

        print(f"Retrieved {len(all_properties)} properties so far...")

    return all_properties

# Usage
all_active_properties = paginate_properties()
print(f"Total: {len(all_active_properties)} active properties")

class PropertyPaginator:
    """Helper class for page-based property navigation."""

    def __init__(self, filter_query="StandardStatus eq 'Active'", page_size=50):
        self.filter_query = filter_query
        self.page_size = page_size
        self.client = WFRMLSClient()

    def get_page(self, page_number: int) -> dict:
        """Get specific page of results (1-indexed)."""

        skip = (page_number - 1) * self.page_size

        properties = self.client.property.get_properties(
            filter_query=self.filter_query,
            top=self.page_size,
            skip=skip,
            orderby="ListingId asc",
            count=True
        )

        # Calculate pagination info
        total_count = len(properties)  # This would need to be extracted from metadata
        total_pages = (total_count + self.page_size - 1) // self.page_size

        return {
            'properties': properties,
            'page_number': page_number,
            'page_size': self.page_size,
            'total_count': total_count,
            'total_pages': total_pages,
            'has_next': page_number < total_pages,
            'has_previous': page_number > 1
        }

# Usage
paginator = PropertyPaginator()

# Get first page
page_1 = paginator.get_page(1)
print(f"Page 1: {len(page_1['properties'])} properties")

# Get next page
if page_1['has_next']:
    page_2 = paginator.get_page(2)
    print(f"Page 2: {len(page_2['properties'])} properties")

# ❌ Inefficient - retrieves all fields
all_fields = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'",
    top=100
)

# ✅ Efficient - only needed fields
minimal_fields = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'",
    select=["ListingId", "ListPrice", "Address", "City"],
    top=100
)

# Field sets for different use cases
FIELD_SETS = {
    'list_view': [
        'ListingId', 'ListPrice', 'Address', 'City', 'BedroomsTotal',
        'BathroomsTotalInteger', 'SquareFeet'
    ],
    'map_view': [
        'ListingId', 'ListPrice', 'Address', 'Latitude', 'Longitude'
    ],
    'detail_view': [
        'ListingId', 'ListPrice', 'Address', 'City', 'PostalCode',
        'BedroomsTotal', 'BathroomsTotalInteger', 'SquareFeet',
        'YearBuilt', 'PropertyType', 'PublicRemarks'
    ]
}

# Use appropriate field set
list_properties = client.property.get_properties(
    filter_query="StandardStatus eq 'Active'",
    select=FIELD_SETS['list_view'],
    top=50
)

# ❌ Slow - expensive string operations
slow_query = client.property.get_properties(
    filter_query="contains(tolower(PublicRemarks), 'pool') and StandardStatus eq 'Active'"
)

# ✅ Fast - indexed fields first
fast_query = client.property.get_properties(
    filter_query="StandardStatus eq 'Active' and contains(PublicRemarks, 'pool')"
)

# ❌ Slow - complex calculations in filter
slow_calc = client.property.get_properties(
    filter_query="(ListPrice div SquareFeet) le 200"
)

# ✅ Fast - use client-side filtering for complex calculations
properties = client.property.get_properties(
    filter_query="StandardStatus eq 'Active' and SquareFeet gt 0",
    select=["ListingId", "ListPrice", "SquareFeet"]
)

# Filter client-side
affordable_per_sqft = [
    prop for prop in properties 
    if (prop['ListPrice'] / prop['SquareFeet']) <= 200
]

from wfrmls.exceptions import (
    ValidationError, NotFoundError, AuthenticationError, 
    RateLimitError, WFRMLSError
)

def robust_property_search(filter_query, **kwargs):
    """Property search with comprehensive error handling."""

    try:
        return client.property.get_properties(
            filter_query=filter_query,
            **kwargs
        )

    except ValidationError as e:
        print(f"❌ Invalid query parameters: {e}")
        # Log the problematic filter query
        print(f"Filter: {filter_query}")
        return []

    except AuthenticationError:
        print("❌ Authentication failed - check API credentials")
        return []

    except RateLimitError as e:
        print(f"❌ Rate limit exceeded: {e}")
        # Could implement retry logic here
        return []

    except WFRMLSError as e:
        print(f"❌ API error: {e}")
        return []

# Usage with validation
def safe_property_lookup(listing_id):
    """Safe property lookup with validation."""

    # Validate listing ID format
    if not isinstance(listing_id, str) or len(listing_id) != 8:
        print("❌ Invalid listing ID format (should be 8-character string)")
        return None

    try:
        return client.property.get_property(listing_id)

    except NotFoundError:
        print(f"❌ Property {listing_id} not found")
        return None

    except Exception as e:
        print(f"❌ Unexpected error: {e}")
        return None

# Examples
properties = robust_property_search("StandardStatus eq 'Active'", top=10)
property_detail = safe_property_lookup("12345678")