API illustration

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:

ParameterDescriptionRequired
zws-idThe 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 IDYes
cityThe name of a cityNo
stateThe two-letter abbreviation for a stateNo
neighborhoodThe name of the neighborhoodNo
zipThe 5-digit ZIP codeNo
unit-typeA string value that specifies whether to show the percent change, parameter value of "percent," or dollar change, parameter value of "dollar"Yes
widthAn integer value that specifies the width of the generated image; the value must be between 200 and 600, inclusiveNo
heightAn integer value that specifies the height of the generated image; the value must be between 100 and 300, inclusiveNo
chartDurationThe 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:

ParameterDescription
urlThe API returns a url to an image showing the chart as specified in the API call
linkThe API returns a url to the corresponding region's local page, if available.
zindexThe API also returns the latest Zindex value for the region.
Limit-warningIf 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.

Example of a Zindex Region Chart

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 codeDescriptionResolution
0Request successfully processed
1Service error-there was a server-side error while processing the requestCheck to see if your url is properly formed: delimiters, character cases, etc
2The specified ZWSID parameter was invalid or not specified in the requestCheck 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.
3Web services are currently unavailable The Zillow Web Service is currently not available. Please come back later and try again.
4The API call is currently unavailableThe Zillow Web Service is currently not available. Please come back later and try again.
500Invalid region name parameter or combination of region parametersThe region parameter was not formed correctly. Check the region parameters section above to see if your region is specified in the right format.
501Region name not foundThe region name you specified was not found. Check if you spelled it correctly.
502Invalid or missing unit-type parameterCheck 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."
503The specified width parameter was invalid (not an integer) or out of boundsThe width parameter has to be within the range 200 to 600, inclusive. Check if you have specified it within this range.
504The specified height parameter was invalid (not an integer) or out of boundsThe height parameter has to be within the range 100 to 300, inclusive. Check if you have specified it within this range.
505No Zindex available for the specified regionWe'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>
                    

Have a question? Find help from a Pro here.