Zillow API Network
GetRegionChart API
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:
http://www.zillow.com/webservice/GetRegionChart.htm
The parameters to 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 | 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:
| Parameter | Description |
|---|---|
| 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: <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. |
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.
Region parameters
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:
| 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 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. |
Sample Calls
Below is a sample call to the API for the city Seattle and state WA with a width of 300 and height of 150:
http://www.zillow.com/webservice/GetRegionChart.htm?zws-id=<ZWSID>&city=seattle&state=WA&unit-type=percent&width=300&height=150
Sample Output
<RegionChart:regionchart xsi:schemaLocation="http://www.zillow.com/static/xsd/RegionChart.xsd /vstatic/4ca2dd187d616abeef3653e6d53b0ff8/static/xsd/RegionChart.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:RegionChart="http://www.zillow.com/static/xsd/RegionChart.xsd"> <request> <city>lacey</city> <state>WA</state> <unit-type>percent</unit-type> <width>300</width> <height>150</height> </request> <message> <text>Request successfully processed</text> <code>0</code> </message> <response> <url>http://localhost:8080/app?chartDuration=1year&chartType=partner&cityRegionId=5470&countyRegionId=0&height=150&nationRegionId=0&page=webservice%2FGetRegionChart&service=chart&showCity=true&showPercent=true&stateRegionId=0&width=300&zipRegionId=0</url> <zindex currency="USD">463115</zindex> </response> </RegionChart:regionchart>
XML Schema Definition (XSD)
The XSD for the API can be found at: http://www.zillow.com/static/xsd/RegionChart.xsd
<xsd:schema attributeFormDefault="unqualified"
elementFormDefault="unqualified"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ZillowTypes="http://www.zillow.com/vstatic/2/static/xsd/ZillowTypes.xsd"
targetNamespace="http://www.zillow.com/vstatic/2/static/xsd/RegionChart.xsd">
<xsd:import namespace="http://www.zillow.com/vstatic/2/static/xsd/ZillowTypes.xsd" />
<xsd:element name="regionchart">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="request">
<xsd:complexType>
<xsd:sequence>
<!-- the region name can be a zip code OR city, two-letter state OR two-letter state
if none of these 3 values occur, the chart for US is returned -->
<xsd:element name="city" type="xsd:string" minOccurs="0"/>
<xsd:element name="state" type="xsd:string" minOccurs="0"/>
<xsd:element name="neighborhood" type="xsd:string" minOccurs="0"/>
<xsd:element name="zip" type="xsd:string" minOccurs="0"/>
<xsd:element name="unit-type" type="xsd:string"/>
<xsd:element minOccurs="0" name="width" type="xsd:string"/>
<xsd:element minOccurs="0" name="height" 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="url" type="xsd:string"/>
<:element name="link" type="xsd:string" minOccurs="0" />
<xsd:element name="zindex">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="type" type="xsd:string" />
<xsd:attribute name="currency" type="xsd:string" default="USD" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>