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.
| 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. Click here to get yours. | Yes |
| price | The price of the property for which monthly payment data will be calculated. | Yes |
| down | The 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 |
| dollarsdown | The 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 |
| zip | The ZIP code in which the property is located. If omitted, monthly property tax and hazard insurance data will not be returned. | No |
| output | The type of output desired. Specify 'xml' for XML output and 'json' for JSON output. If omitted, 'xml' is assumed. | No |
| callback | The 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 |
| Parameter | Description |
|---|---|
| Payments | The monthly principal and interest payment and current loan rate for each of:
|
| Down payment | The 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 taxes | If a ZIP code was supplied, the estimated monthly property tax payment is returned. |
| Monthly hazard insurance | If a ZIP code was supplied, the estimated monthly hazard insurance payment is returned. |
| 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>
This output field will not be returned if it is false.
|
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 with 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 | An invalid price was specified | Make sure the 'price' parameter is specified and is a valid integer. |
| 501 | An invalid ZIP code was specified | Make sure the 'zip' parameter is specified and is a valid five digit ZIP code. |
| 502 | An invalid down payment percentage or dollar amount was specified | Make sure the 'down' or 'dollarsdown' parameter is specified and is a valid integer. |
| 503 | Rate data unavailable | Zillow Mortgage Marketplace rate data is currently unavailable. Please come back later and try again. |
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
<?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
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.
