Resolve a Compass listing by street address
compass_get_by_addressResolve a free-text street address to a Compass listing's canonical URL and identifiers, with verification across multiple search rungs.
Instructions
Resolve a free-text street address to a Compass listing's canonical URL and identifiers in one call. Walks three rungs: first the structured typeahead POST /api/v3/omnisuggest/autocomplete (the primary rung — Compass's address-suggest API, which routes around the AWS WAF that 403s the SSR free-text path, issues #78/#79), then /homes-for-sale/?q=<address> (the free-text rung) and — when those return no verified match — a slug-based search at /homes-for-sale/<city-state-or-zip>/ (the search-fallback rung, issue #71). Each candidate is verified against the query (case + street-type abbreviation normalization, then whole-token equality, issue #45) before being accepted. Returns { url, listing_id_sha, pid, address, resolved, matched_via } where matched_via is "typeahead", "freetext", or "search_fallback" so callers can see which rung found the match. When no rung matches, returns { resolved: false, error: "no listing matched" } rather than leaking a wrong URL. The url is the stable _pid/ form when Compass provides a navigationPageLink (preferred for trackers/bookmarks — sha URLs go stale on relisting), falling back to the _lid/ form otherwise. Read-only; safe to call repeatedly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ZIP code, e.g. "28746" | |
| city | No | e.g. "Lake Lure" | |
| state | No | Two-letter state abbreviation, e.g. "NC" | |
| address | Yes | Street address line, e.g. "126 Sleeping Bear Ln". |