Resolve a street address to a homes.com property URL
homes_get_by_addressResolve a US street address to a canonical homes.com property URL and opaque hash. Uses typeahead, slug, or search fallback with optional price bounds.
Instructions
Resolve a US street address to its canonical homes.com property URL + opaque property hash. Pass address (street), city, state, and optional zip. Walks three rungs: first the structured smartsearch typeahead (POST /routes/res/consumer/smartsearch/autocomplete/ — the primary rung, the same address-suggest API homes.com's search box fires, returning the real /property/// URL directly), then a slug-routed page (parsing the embedded Schema.org JSON-LD — both the CollectionPage search-results shape and the single-RealEstateListing detail redirect), and finally a city/zip search page with street-token fuzzy match. Every candidate is verified against the input with a whole-token street match (plus a unit guard so a multi-unit building resolves to the exact unit, not a neighbour). Optional price_min / price_max (USD) bound ONLY the city/zip search-fallback rung — when an address is ambiguous or the typeahead misses and you know the listing's rough price, this narrows the area search (homes.com ?price-min=/?price-max= filter) so the fuzzy matcher picks from fewer, more-relevant candidates; omit for unchanged unbounded behaviour. Returns { url, property_hash, street_address, matched_via, resolved: true } on success — matched_via is 'typeahead' for the structured-API hit, 'slug' for a direct routing hit, 'search_fallback' for the search-page fuzzy match — or { resolved: false, error: 'no listing found' } when homes.com has no match (so the higher-level unified canonical-URL lookup can degrade gracefully). KNOWN FAILURE MODE: rural addresses and very-new construction can still miss because homes.com hasn't indexed them yet. Compare the returned street_address against your input to confirm. For larger batches (≥ 3 addresses), prefer homes_resolve_addresses. Read-only; safe to call repeatedly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ZIP code (optional; improves precision when present). | |
| city | Yes | City (e.g. "Lake Lure"). | |
| state | Yes | 2-letter US state code (e.g. "NC"). | |
| address | Yes | Street address (e.g. "126 Sleeping Bear Ln"). | |
| price_max | No | Optional upper price bound (USD). Applied ONLY to the search-fallback rung (homes.com's `?price-max=` filter). Useful when an address is ambiguous or the typeahead misses and you know the listing's rough price — improves disambiguation/recall. Omit for unbounded fallback. | |
| price_min | No | Optional lower price bound (USD). Applied ONLY to the city/zip search-fallback rung — bounds that area search with homes.com's `?price-min=` filter so an ambiguous address resolves against a narrower candidate set. Ignored by the typeahead/slug rungs (a single known address has nothing to narrow). Omit for unbounded fallback. Must be <= price_max when both are given. |