Zillow API address lookup: avoid the wrong property
Build safer Zillow address lookups with unit numbers, identity checks, and explicit handling for ambiguous property matches.
An address match is an identity decision
A Zillow API address lookup should resolve the property your user meant, including the unit when one exists. A nearby home with a similar street name is not an acceptable substitute. In PropertiesAPI, an ambiguous match can return 409 address_ambiguous so your application can ask for a correction.
Use a full US address with a house number, street, city and state or ZIP code. Keep the original input as well as any normalized version. That makes it possible to show the user what changed and investigate a mismatch without silently overwriting their request.
Prepare an address without destroying information
Trim extra whitespace, but preserve directional words, building numbers and unit identifiers. “North” and “South” may refer to different streets. “Apartment 4” and a building without a unit can identify different records. A ZIP code helps narrow a match but does not replace the street address.
- Include the unit for apartments and condominiums.
- Retain a user-entered address separately from the returned canonical address.
- Use URL encoding rather than assembling a query string by hand.
- Send exactly one lookup input: address, url or zpid.
Send a single-property request
This request uses the documented PropertiesAPI endpoint. Replace the environment variables with your own server-side key and the address you want to check. The example shows the request contract, not a guarantee that an arbitrary address has a matching record.
curl --get 'https://api.propertiesapi.com/v1/zillow/property' --header "x-api-key: $PROPERTIESAPI_KEY" --data-urlencode "address=$PROPERTY_ADDRESS" --max-time 130Handle ambiguous matches explicitly
When the API returns address_ambiguous, inspect the error details and compare the candidate with the requested home. A candidate link is a review aid. Do not automatically fetch it and label it as the requested property.
Offer the user two useful actions: edit the address, or confirm a specific Zillow property link after checking it. Preserve the original input in your application record. An apartment-building page may describe a building rather than the individual unit the user intended.
A not_found response means the lookup did not find a match. It should not cause your application to remove the unit number and retry a broader address without telling the user. That fallback can turn a clear failure into an apparently successful result for the wrong home.
Check successful responses too
For a successful response, compare data.zpid, data.detailUrl and the address components with your expected identity. Inspect any meta.warning before using the result automatically. Store the returned identity with the data instead of treating the input address as proof of the match.
A practical review queue separates confirmed matches, ambiguous candidates and missing results. Downstream exports and analysis should consume confirmed records. This avoids mixing uncertain matches into a portfolio valuation or a customer-facing property page.
| Outcome | Application action |
|---|---|
| 200 with expected identity | Store the returned identity and collection timestamp. |
| 409 address_ambiguous | Ask for a corrected address or explicit candidate confirmation. |
| 404 not_found | Keep the original request and show a clear missing-result state. |
| 400 bad_param | Correct the input before sending another request. |
Evaluate matching with realistic cases
Test addresses with unit numbers, directional street names, abbreviated road types and incomplete location information. Record failures as well as successes. A test suite that contains only detached houses on uniquely named streets will miss the cases most likely to produce a costly mismatch.
Sources and documentation
Product details checked against the linked documentation on October 21, 2026. Code and sample inputs are illustrative unless stated otherwise.
Written by PropertiesAPI, an independent property data service. We are not affiliated with Zillow. Source data may be incomplete or change over time.