Zillow API Network
The GetRegionChart API generates a URL for an image file that displays the historical Zestimates for a specific geographic region. The API accepts as input the name of the region as well as a chart type: either percentage or dollar value change. Optionally, the API accepts width and height parameters that constrain the size of the image. The historical data can be for the past 1 year, 5 years or 10 years.
The GetRegionChart Web Service is located at:
The parameters to the API are:
|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||Yes|
|city||The name of a city||No|
|state||The two-letter abbreviation for a state||No|
|neighborhood||The name of the neighborhood||No|
|zip||The 5-digit ZIP code||No|
|unit-type||A string value that specifies whether to show the percent change, parameter value of "percent," or dollar change, parameter value of "dollar"||Yes|
|width||An integer value that specifies the width of the generated image; the value must be between 200 and 600, inclusive||No|
|height||An integer value that specifies the height of the generated image; the value must be between 100 and 300, inclusive||No|
|chartDuration||The duration of past data that needs to be shown in the chart. Valid values are "1year", "5years" and "10years". If unspecified, the value defaults to "1year".||No|
The result set of the API:
|url||The API returns a url to an image showing the chart as specified in the API call|
|link||The API returns a url to the corresponding region's local page, if available.|
|zindex||The API also returns the latest Zindex value for the region.|
|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:|
<text>Request successfully processed</text>
This output field will not be returned if it is false.
The output url provided by the API points to an image like the one shown below. You can always tweak the size of the image using the height/width parameters so that they fit your site requirements.
The API expects the region parameters to be provided in a particular way. These are the valid combinations of region parameters you can provide:
zip - returns the chart for the ZIP code region, if found
state - returns the chart for the state, if found
city and state - returns the chart for the city, if found. Include the state; city name alone cannot be given.
neighborhood, city, and state - returns the chart for the neighborhood, if found. Include the city and state; neighborhood name alone cannot be given.
none - returns the chart for the U.S.
Messages and Codes
The following table summarizes possible return codes from the API:
|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 region name parameter or combination of region parameters||The region parameter was not formed correctly. Check the region parameters section above to see if your region is specified in the right format.|
|501||Region name not found||The region name you specified was not found. Check if you spelled it correctly.|
|502||Invalid or missing unit-type parameter||Check if you have specified the unit-type. This is mandatory. If you have specified it, check if the unit type is either "percent" or "dollar."|
|503||The specified width parameter was invalid (not an integer) or out of bounds||The width parameter has to be within the range 200 to 600, inclusive. Check if you have specified it within this range.|
|504||The specified height parameter was invalid (not an integer) or out of bounds||The height parameter has to be within the range 100 to 300, inclusive. Check if you have specified it within this range.|
|505||No Zindex available for the specified region||We're sorry, but there is no Zindex data available for the region you specified. See our Zestimate coverage tables.|
XML Schema Definition (XSD)
The XSD for the API can be found at: http://www.zillow.com/static/xsd/RegionChart.xsd