API illustration

Zillow API Network

GetMonthlyPayments API

For a specific loan amount, the GetMonthlyPayments API returns the estimated monthly payment that includes principal and interest based on today's mortgage rate. The API returns the estimated monthly payment per loan type (30-year fixed, 15-year fixed, and 5/1 ARM). If a ZIP code is entered, the estimated taxes and insurance are returned in the result set.

The GetMonthlyPayments API Web Service is located at: http://www.zillow.com/webservice/GetMonthlyPayments.htm

See reference code for a sample monthly payment and rates widget at: http://www.zillow.com/howto/api/GetMonthlyPaymentsWidgetExample.htm

Also, check out Zillow's prebuilt mortgage calculator widget.

The parameters of 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 ID. Click here to get yours. Yes
priceThe price of the property for which monthly payment data will be calculated. Yes
downThe percentage of the total property price that will be placed as a down payment. If omitted, a 20% down payment is assumed. If the down payment is less than 20%, a monthly private mortgage insurance amount is specified for each returned loan type. No
dollarsdownThe dollar amount that will be placed as a down payment. This amount will be used for the down payment if the 'down' parameter is omitted. If the down payment is less than 20% of the purchase price, a monthly private mortgage insurance amount is specified for each returned loan type. No
zipThe ZIP code in which the property is located. If omitted, monthly property tax and hazard insurance data will not be returned. No
outputThe type of output desired. Specify 'xml' for XML output and 'json' for JSON output. If omitted, 'xml' is assumed. No
callbackThe name of the JavaScript callback function used to process the returned JSON data. If specified, the returned JSON will be wrapped in a function call with the specified function name. This parameter is intended for use with dynamic script tags. The callback function is only used for JSON output. No

The API result set:

ParameterDescription
PaymentsThe monthly principal and interest payment and current loan rate for each of:
  • 30 year fixed rate loans
  • 15 year fixed rate loans
  • 5/1 adjustable rate loans
If the down payment is less than 20%, the monthly private mortgage insurance payment is listed as well.
Down paymentThe down payment amount in dollars either calculated from the supplied down payment percentage (or the default 20%) or taken from the down payment dollar amount (if provided).
Monthly property taxesIf a ZIP code was supplied, the estimated monthly property tax payment is returned.
Monthly hazard insuranceIf a ZIP code was supplied, the estimated monthly hazard insurance payment is returned.
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.

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 with 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.
500An invalid price was specifiedMake sure the 'price' parameter is specified and is a valid integer.
501An invalid ZIP code was specifiedMake sure the 'zip' parameter is specified and is a valid five digit ZIP code.
502An invalid down payment percentage or dollar amount was specifiedMake sure the 'down' or 'dollarsdown' parameter is specified and is a valid integer.
503Rate data unavailableZillow Mortgage Marketplace rate data is currently unavailable. Please come back later and try again.

Sample API Calls

Below is an example call to the API returning XML data:
http://www.zillow.com/webservice/GetMonthlyPayments.htm?zws-id=<ZWSID>&price=300000&down=15&zip=98104

Sample API Output (XML)

    <?xml version="1.0" encoding="utf-8" ?>
    <MonthlyPayments:paymentsSummary xsi:schemaLocation="http://www.zillow.com/static/xsd/MonthlyPayments.xsd /vstatic/845208ab51683ebd44471c61c4cdadf1/static/xsd/MonthlyPayments.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:MonthlyPayments="http://www.zillow.com/static/xsd/MonthlyPayments.xsd">
    <request>
        <price>300000</price>
        <down>15</down>
        <zip>98104</zip>
    </request>
    <message>
       <text>Request successfully processed</text>
       <code>0</code>
    </message>
    <response>
        <payment loanType="thirtyYearFixed">
            <rate>5.9</rate>
            <monthlyPrincipalAndInterest>1512</monthlyPrincipalAndInterest>
            <monthlyMortgageInsurance>68</monthlyMortgageInsurance>
        </payment>
        <payment loanType="fifteenYearFixed">
            <rate>5.68</rate>
            <monthlyPrincipalAndInterest>1477</monthlyPrincipalAndInterest>
            <monthlyMortgageInsurance>68</monthlyMortgageInsurance>
        </payment>
        <payment loanType="fiveOneARM">
            <rate>5.71</rate>
            <monthlyPrincipalAndInterest>1482</monthlyPrincipalAndInterest>
            <monthlyMortgageInsurance>74</monthlyMortgageInsurance>
        </payment>
        <downPayment>45000</downPayment>
        <monthlyPropertyTaxes>193</monthlyPropertyTaxes>
        <monthlyHazardInsurance>49</monthlyHazardInsurance>
    </response>
    </MonthlyPayments:paymentsSummary>
                        

Below is an example call to the API returning JSON data:
http://www.zillow.com/webservice/GetMonthlyPayments.htm?zws-id=<ZWSID>&price=300000&down=15&zip=98104&output=json&callback=cb

Sample API Output (JSON)

    cb( {
    "request" : {
        "price" : "300000",
        "down" : "15",
        "zip" : "98104",
        "output" : "json",
        "callback" : "cb"
    },

    "message" : {
        "text" : "Request successfully processed",
        "code" : "0"
    },

    "response" : {
        "thirtyYearFixed" : {
            "rate" : "0.0",
            "monthlyPrincipalAndInterest" : "0",
            "monthlyMortgageInsurance" : "68"
        },

        "fifteenYearFixed" : {
            "rate" : "0.0",
            "monthlyPrincipalAndInterest" : "0",
            "monthlyMortgageInsurance" : "68"
        },

        "fiveOneARM" : {
            "rate" : "0.0",
            "monthlyPrincipalAndInterest" : "0",
            "monthlyMortgageInsurance" : "70"
        },

        "downPayment" : "45000",
        "monthlyPropertyTaxes" : "20",
        "monthlyHazardInsurance" : "49"
    }
    } );
                        

Have a question? Find help from a Pro here.