Zillow API Network
GetDeepSearch-Results API
The GetDeepSearchResults API finds a property for a specified address (or, if no exact match for a property is found, a list of closely matching properties is returned). The result set returned contains the full address(s), zpid and Zestimate data that is provided by the GetSearchResults API. Moreover, this API call also gives rich property data like lot size, year built, bath/beds, last sale details etc.
The GetSearchResults API Web Service is located at: http://www.zillow.com/webservice/GetDeepSearchResults.htm
The parameters of the API are:
| Parameter | Description | Required |
|---|---|---|
| zws-id | The Zillow Web Service Identifier. Each subscriber to Zillow Web Services is uniquely identified by an ID sequence and every request to Web services requires this ID. Click here to get yours. | Yes |
| address | The address of the property to search. This string should be URL encoded. | Yes |
| citystatezip | The city+state combination and/or ZIP code for which to search. This string should be URL encoded. Note that giving both city and state is required. Using just one will not work. | Yes |
The API result set:
| Parameter | Description |
|---|---|
| zpid | The Zillow Property ID. Other API calls use this zpid to identify properties, and to retrieve property-specific data. |
| Links |
URLs to specific Zillow pages for this property:
|
| Full address |
The complete address for the property:
|
| Zestimate data |
Zestimate related data:
|
| FIPScounty | The FIPS county code is a five-digit Federal Information Processing Standard (FIPS) code (FIPS 6-4) which uniquely identifies counties and county equivalents in the United States, certain U.S. possessions, and certain freely associated states. The first two digits are the FIPS state code and the last three are the county code within the state or possession. |
| Usecode |
This code specifies the type of home. The list of codes and the type of home they stand for are given below:
|
| Tax assessment year | The year of the most recent tax assessment |
| Tax assessment | The most recent tax assessment |
| Yearbuilt | The year in which the property was constructed. |
| lotsizeSqFt | The size of the lot in sq. ft. |
| finishedSqFt | The size of the finished property in sq. ft. |
| Bathrooms | Number of bathrooms in the property. |
| Bedrooms | Number of bedrooms in the property. |
| LastSoldDate | The date of last sale for this property. |
| LastSoldPrice | The price of the last sale for this property. |
| Limit-warning |
If this field is set to "true", it means you are approaching your call limit. It appears under the 'message' element in the API result set: <message> <text>Request successfully processed</text> <code>0</code> <limit-warning>true</limit-warning> </message> This output field will not be returned if it is false. |
Messages and Codes
The following table summarizes possible return codes from the API:
| Error code | Description | Resolution |
|---|---|---|
| 0 | Request successfully processed | |
| 1 | Service error-there was a server-side error while processing the request | Check to see if your url is properly formed: delimiters, character cases, etc |
| 2 | The specified ZWSID parameter was invalid or not specified in the request | Check if you have provided a ZWSID in your API call. If yes, check if the ZWSID is keyed in correctly. If it still doesn't work, contact Zillow to get help on fixing your ZWSID. |
| 3 | Web services are currently unavailable | The Zillow Web Service is currently not available. Please come back later and try again. |
| 4 | The API call is currently unavailable | The Zillow Web Service is currently not available. Please come back later and try again. |
| 500 | Invalid or missing address parameter | Check if the input address parameter matches the format specified in the input parameters table. When inputting a city name, the state should also be given. A city name alone will not give a valid address. |
| 501 | Invalid or missing citystatezip parameter | Same as error 500. |
| 502 | No results found | Sorry, the address you provided is not found in the Zillow property database. |
| 503 | Failed to resolve city, state or ZIP code | Check if the city-state combination is valid. Also check if you have provided a valid ZIP code. |
| 504 | No coverage for specified area | The specified area is not covered by the Zillow property database. To see our property coverage tables, click here. |
| 505 | Timeout | Your request timed out. The server could be busy or unavailable. Try again later. |
| 506 | Address string too long | If address is valid, try using abbreviations. |
| 507 | No exact match found. | Verify that the given address is correct. |
Sample Calls
Below is an example of calling the API for the address for the exact address match "2114 Bigelow Ave", "Seattle, WA":
http://www.zillow.com/webservice/GetDeepSearchResults.htm?zws-id=<ZWSID>&address=2114+Bigelow+Ave&citystatezip=Seattle%2C+WA
Sample Output
<?xml version="1.0" encoding="utf-8" ?> <SearchResults:searchresults xmlns:SearchResults="http://www. zillow.com/vstatic/3/static/xsd/SearchResults.xsd"> <request> <address>2114 Bigelow Ave</address> <citystatezip>Seattle, WA</citystatezip> </request> <message> <text>Request successfully processed</text> <code>0</code> </message> <response> <results> <result> <zpid>48749425</zpid> <links> <homedetails>http://www.zillow.com/HomeDetails.htm?city=SEATTLE+&state=WA&zprop=48749425&partner=<ZWSID></homedetails> <graphsanddata>http://www.zillow.com/Charts.htm?chartDuration=1year&zpid=48749425&cbt=2415898876184807661%7E8%7ElTavs39pxTksNXvTttdAthD3QnLDhCU%2B476WWlb99DE%3D&partner=<ZWSID></graphsanddata> <mapthishome>http://www.zillow.com/search/Search.htm?mode=search&zpid=48749425&partner=<ZWSID></mapthishome> <myestimator>http://www.zillow.com/myestimator/Intro.htm?zprop=48749425&partner=<ZWSID></myestimator> <myzestimator deprecated="true">http://www.zillow.com/myestimator/Intro.htm?zprop=48749425&partner=<ZWSID></myzestimator> </links> <address> <street>2114 Bigelow Ave N</street> <zipcode>98109</zipcode> <city>SEATTLE</city> <state>WA</state> <latitude>47.637934</latitude> <longitude>-122.347936</longitude> </address> <FIPScounty>033</FIPScounty> <useCode>SingleFamily</useCode> <yearBuilt>1924</yearBuilt> <lotSizeSqFt>4680</lotSizeSqFt> <finishedSqFt>3290</finishedSqFt> <bathrooms>2.75</bathrooms> <bedrooms>4</bedrooms> <lastSoldDate>06/18/2002</lastSoldDate> <lastSoldPrice currency="USD">770000</lastSoldPrice> <valuation> <amount currency="USD">1091061</amount> <last-updated>05/26/2006</last-updated> <oneWeekChange currency="USD">61096</oneWeekChange> <valuationRange> <low currency="USD">938312</low> <high currency="USD">1200167</high> </valuationRange> <percentile /> </valuation> </result> </results> </response> </SearchResults:searchresults> <!-- H:33 T:19ms S:1462 R:Tue Sep 12 19:21:14 UTC 2006 B:2.0.11690_060911_1 -->
XML Schema Definition (XSD)
The XSD for the API is located at: http://www.zillow.com/static/xsd/SearchResults.xsd
<?xml version="1.0" encoding="utf-8" ?> <xsd:schema attributeFormDefault="unqualified" elementFormDefault="unqualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ZillowTypes="http://www.zillow.com/vstatic/3/static/xsd/ZillowTypes.xsd" targetNamespace="http://www.zillow.com/vstatic/3/static/xsd/SearchResults.xsd"> <xsd:import namespace="http://www.zillow.com/vstatic/3/static/xsd/ZillowTypes.xsd" /> <xsd:element name="searchresults"> <xsd:complexType> <xsd:sequence> <xsd:element name="request"> <xsd:complexType> <xsd:sequence> <xsd:element name="address" type="xsd:string" /> <xsd:element name="citystatezip" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="message" type="ZillowTypes:Message" /> <xsd:element minOccurs="0" name="response"> <xsd:complexType> <xsd:sequence> <xsd:element name="results"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="unbounded" name="result" type="ZillowTypes:SimpleProperty" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
