Property Data SDK

from datafiniti.property import PropertyDataSDK

sdk = PropertyDataSDK.from_env()

response = sdk.search_by_address(
    address="712 liard river rd",
    postal_code="78634",
)

print("
=== ADDRESS SEARCH TEST ===")
print("Matches:", response.get("num_found"))

records = response.get("records", [])

if records:
    property_record = records[0]
    print("
Property:")
    print(property_record.get("address"))
    print(property_record.get("city"))
    print(property_record.get("province"))
else:
    print("No property found.")

from datafiniti.property import PropertyDataSDK

sdk = PropertyDataSDK.from_env()

count = sdk.count('country:US AND mostRecentStatus:"For Sale"')

print("
=== COUNT TEST ===")
print(f"Properties found: {count:,}")

from datafiniti.property import PropertyDataSDK

sdk = PropertyDataSDK.from_env()

# Search for properties within 10 miles of downtown Austin, TX
# geoLocation format: [Longitude, Latitude, Distance, Unit]
# Supported units: m, mi, ft, yd, mm, km, NM, cm
response = sdk.geolocation(
    longitude=-97.7430600,
    latitude=30.2671500,
    distance=10,
    unit="mi",
    num_records=5,
    view=[
        {"name": "address"},
        {"name": "city"},
        {"name": "country"},
        {"name": "geoLocation"},
        {"name": "mostRecentStatus"},
        {"name": "mostRecentStatusDate"},
        {"name": "mostRecentStatusFirstDateSeen"},
        {"name": "postalCode"},
    ],
)

print("
=== GEOLOCATION SEARCH ===")
print(f"Total matches: {response.get('num_found'):,}")

records = response.get("records", [])

for prop in records:
    print(
        f"
{prop.get('address')}, {prop.get('city')} {prop.get('postalCode')}"
        f" — {prop.get('mostRecentStatus')}"
        f"
--geoLocation: {prop.get('geoLocation')}"
    )

from datafiniti.property import PropertyDataSDK

sdk = PropertyDataSDK.from_env()

print("
=== PAGINATION TEST ===")

records_seen = 0

for property_record in sdk.paginate(
    query="country:US",
    page_size=10,
    max_records=25,
):
    records_seen += 1
    print(f"{records_seen}. {property_record.get('address', 'Unknown Address')}")

print(f"
Total Retrieved: {records_seen}")

"""
Property Views Example: E-Commerce Vacant House Check

Uses a custom view to fetch only the fields needed to determine whether a
shipping address matches a vacant or off-market property — a common signal
for potentially fraudulent e-commerce orders.

Reference: https://docs.datafiniti.co/docs/identify-e-commerce-orders-shipping-to-vacant-houses
"""

from datafiniti.property import PropertyDataSDK

# ---------------------------------------------------------------------------
# View options
#
# OPTION 1 (used below): Custom inline view
#   Pass a list of field objects directly in the request. No setup required.
#   Reference: https://docs.datafiniti.co/docs/using-a-custom-property-view
#
# OPTION 2: Premade (named) view — pass a string instead of a list.
#   "default"               All fields (same as omitting view entirely).
#                           Note: imageURLs and sourceURLs are excluded from
#                           default; use a preset or custom view for those.
#   "property_flat_prices"  All fields; one CSV row per price entry.
#   "property_flat_reviews" All fields; one CSV row per review.
#   "residential"           Residential-focused fields — includes absenteeOwner,
#                           assessedValues, ownerName, statuses, transactions, etc.
#   Example: sdk.search(query, view="residential", num_records=10)
#   Reference: https://docs.datafiniti.co/docs/available-views-for-property-data
# ---------------------------------------------------------------------------

PROPERTY_VIEW = [
    {"name": "address"},
    {"name": "city"},
    {"name": "province"},
    {"name": "postalCode"},
    {"name": "mostRecentStatus"},
    {"name": "mostRecentStatusDate"},
    {"name": "mostRecentRentalStatus"},
    {"name": "mostRecentRentalStatusDate"},
]

ON_MARKET_STATUSES = {"For Sale", "Coming Soon", "Pending", "For Rent", "For Sale or Rent"}

def market_status(record):
    sale = record.get("mostRecentStatus", "")
    rental = record.get("mostRecentRentalStatus", "")
    if sale in ON_MARKET_STATUSES:
        return "On Market", record.get("mostRecentStatusDate", "N/A")
    if rental in ON_MARKET_STATUSES:
        return "On Market", record.get("mostRecentRentalStatusDate", "N/A")
    date = record.get("mostRecentStatusDate") or record.get("mostRecentRentalStatusDate", "N/A")
    return "Off Market", date

def check_address(sdk, address, city, province, postal_code):
    query = (
        f'address:"{address}"'
        f" AND city:{city}"
        f" AND province:{province}"
        f' AND postalCode:"{postal_code}"'
        f" AND country:US"
    )
    response = sdk.search(query, num_records=1, view=PROPERTY_VIEW)
    records = response.get("records", [])
    return records[0] if records else None

if __name__ == "__main__":
    # Sample shipping addresses from incoming orders.
    # Normalize street designations before querying — Datafiniti uses
    # abbreviations: "Ave" not "Avenue", "St" not "Street", "Dr" not "Drive".
    addresses = [
        {"address": "200 Tennyson Ave",       "city": "Pittsburgh", "province": "PA", "postal_code": "15213"},
        {"address": "4616 Howard Ln UNIT 550", "city": "Austin",     "province": "TX", "postal_code": "78728"},
        {"address": "1023 Grassy Field Rd",    "city": "Austin",     "province": "TX", "postal_code": "78737"},
    ]

    sdk = PropertyDataSDK.from_env()

    print("
=== VACANT HOUSE CHECK ===
")

    for entry in addresses:
        print(f"{entry['address']}, {entry['city']}, {entry['province']} {entry['postal_code']}")

        record = check_address(sdk, **entry)

        if record is None:
            print("  No property record found.
")
            continue

        label, date = market_status(record)
        print(f"  ID:                    {record.get('id', 'N/A')}")
        print(f"  Address:               {record.get('address', 'N/A')}")
        print(f"  City:                  {record.get('city', 'N/A')}")
        print(f"  Province:              {record.get('province', 'N/A')}")
        print(f"  Postal Code:           {record.get('postalCode', 'N/A')}")
        print(f"  Most Recent Status:    {record.get('mostRecentStatus', 'N/A')}")
        print(f"  Most Recent Rental:    {record.get('mostRecentRentalStatus', 'N/A')}")
        print(f"  Status: {label} (as of {date})")
        if label == "Off Market":
            print("  *** FLAGGED — property may be vacant ***")
        print()