Zillow API Network
GetChart API
The GetChart API generates a URL for an image file that displays historical Zestimates for a specific property. The API accepts as input the Zillow Property ID 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 GetChart Web Service is located at http://www.zillow.com/webservice/GetChart.htm
The input parameters for 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 |
| zpid | The Zillow Property ID for the property; the parameter type is an integer | Yes |
| 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. |
| 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.
Messages and Codes
The following table summarizes the 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 | The specified zpid parameter was not specified or invalid | The zpid parameter you have provided is not valid. Please check if your zpid is correct and try again. |
| 501 | The specified unit-type parameter was not specified or invalid | 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." |
| 502 | 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. |
| 503 | 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. |
Sample Calls
Below is a sample call to the API for zpid 48749425 with a width of 300 and height of 150:
http://www.zillow.com/webservice/GetChart.htm?zws-id=<ZWSID>&unit-type=percent&zpid=48749425&width=300&height=150
Sample Output
<?xml version="1.0" encoding="utf-8" ?> <Chart:chart xmlns:Chart="http://www.zillow.com/vstatic/3/static/xsd/Chart.xsd"> <request> <zpid>48749425</zpid> <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://www.zillow.com/app?chartDuration=1year&chartType=partner&height=150&page=webservice%2FGetChart&service=chart&showPercent=true&width=300&zpid=48749425</url> </response> </Chart:chart> <!-- H:11 T:1ms S:311 -->
XML Schema Definition (XSD)
The XSD for the API is located at: http://www.zillow.com/static/xsd/Chart.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/2/static/xsd/ZillowTypes.xsd" targetNamespace="http://www.zillow.com/vstatic/2/static/xsd/Chart.xsd"> <xsd:import namespace="http://www.zillow.com/vstatic/2/static/xsd/ZillowTypes.xsd" /> <xsd:element name="chart"> <xsd:complexType> <xsd:sequence> <xsd:element name="request"> <xsd:complexType> <xsd:sequence> <xsd:element name="zpid" type="xsd:string" /> <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" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
