Resolve a street address to a homes.com property URL
homes_get_by_addressResolve a US street address into its canonical homes.com property URL and property hash. Use it when you need the exact listing link from address, city, state, and optional ZIP, with fallback matching for ambiguous addresses.
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. |