Zillow WordPress Plugin

Posted March 15, 2017

Update: April 10, 2017

I’ve gotten some good feedback on this plugin, many thanks to those of you who have downloaded it, used it and reported bugs. One thing I didn’t notice right away after building the plugin was that the Zillow Web Services call to get reviews was returning old data. In my case, my client had reviews from just a few days prior, but the ZWS API was returning reviews from more than 6 months before.

I reached out to Zillow, and to their credit they responded within an hour and informed me that the ZWS API was not the most current way to get reviews. They instead pointed me to their new mortgage API. After giving it a few test runs with Postman, I confirmed it was returning the latest reviews for my client. It also gives you more flexibility over the response fields. This means you can ask only for the fields you care about, thus keeping the response payloads lean. It also has more flexibility over the number of results. The ZWS API limited you from 3 to 10, while the new API has no such limitations. The one thing that is missing from the new API, however, is the average rating. I liked including this along with specific reviews, but using this new API the average rating would beed to be calculated manually. This would require loading all reviews, which may not be ideal if the Zillow user has a lot.

All in all, the new mortgage API seems to work much better than the equivalent ZWS API. Thus, I have updated the plugin to use the newer API. You’ll need to get a unique partner ID from Zillow, which I was able to do through their support system. It took me about 24 hours to get a response. From there, the plugin should work just like it did before, only the widget options are slightly different.

Hope you enjoy the update! And now back to your original blog reading…

Recently, while working on a project for a client who does mortgage lending, she asked me to incorporate her Zillow reviews into the new site. After quite a bit of searching, I found there were no current Zillow WordPress plugin offerings. As this was an important part of her new site, I set out to create my own. You can download the plugin for free here. Below I’ll discuss some behind the scenes details on what it took to create this plugin.

Zillow Reviews Widgets

Zillow already offers a widget for realtors and mortgage professionals to embed their reviews on websites, but my client and I didn’t like it too much. For starters, the styling felt a little dated and difficult to override. It uses standard Zillow color and fonts, which didn’t match the look and feel of the site I was building. Second, the widget offers no control over the number of reviews and how they are sorted. This was a problem for my client because it was showing her oldest reviews first, which gave the impression she had not been active on Zillow for many years. For these reasons, I decided to build a custom Zillow WordPress plugin.

Zillow API + PHP Library

In addition to the reviews widget, Zillow has a more robust and flexible RESTful API. Among other things, this API lets you get a raw XML or JSON feed of reviews for a realtor or mortgage professional in the Zillow network. To get started, you register for a Zillow Web Service ID (ZWSID). This will generate you a unique alpha-numeric ID that must be passed in with all Zillow API calls. Each Zillow API has its own set of required and optional parameters, but ZWSID is required for all of them. For example, the reviews API, which is the one I was interested in, accepts the following query parameters:

zws-id: Required; Your unique Zillow Web Services ID.
screenname: Optional; The username of the realtor or mortgage professional for which to list reviews.
email: Optional; The e-mail address of the realtor or mortgage professional for which to list reviews.
count: Optional; The number of reviews to list. Default is 3, and maximum is 10.
ouput: Optional; Specifies whether to return JSON or XML output. Default is XML.
returnTeamMemberReviews: Optional; Specifies whether or not to include reviews for team members of the screenname or email specified previously. Default is not to include them.

Note: You must supply at least the screenname or email parameter, but not both.

Even though the Zillow API is easy to understand and can be accessed using any HTTP client library, I was working on a bit of a timeline and didn’t want to write the code completely from scratch. Luckily after some searching I came across this really nice PHP library written for Zillow. Even though the library was almost 5 years old and didn’t include the Zillow Reviews API, I was able to use it as a starting point to accessing the reviews for my client and embedding them using a widget.

Creating WordPress Widgets

To keep things simple, I wanted my Zillow WordPress plugin to provide a single widget that would handle all configuration. This would allow me to place reviews into different sidebars and page areas, and make it easy to configure each area differently if needed (for example, the footer might only show 3 reviews while a page sidebar might show 5). Having never written a WordPress plugin or widget, I first followed this excellent tutorial to get started. Basically there are 2 steps to get started with building a WordPress widget:

Create a new class that extends WP_Widget and override a few methods.
Register an action with the standard widgets_init hook to register your widget with WordPress.

Pretty simple. The code inside the widget class handles all the heavy lifting of calling the Zillow API and manipulating the returned XML to creates a nice HTML widget that displays Zillow reviews.

Building The Zillow WordPress Plugin

Knowing how to access the Zillow API and how to create a simple widget, we can now create a simple Zillow WordPress Plugin that ties it all together. First, I needed to add the Reviews API call since the PHP library I found was written before the Reviews API was available. The code below lives in the Zillow_Api class:

TBD: API call with curl

Next I created an extension of WP_Widget to do everything related to creating the widget, configuring it, and displaying data when WordPress renders it. In this case, the plugin has several configurable fields:

Title: Text to display at the top of the widget.
ZWS ID: Zillow Web Services ID.
Screen Name or Email: Screen Name or e-mail address of Zillow user for which to display reviews.
Number of Reviews: Number of reviews to display.
Include Team Members: Whether or not to include team member reviews along with the user.

With the Zillow WordPress plugin activated, the widget can be placed into any WordPress site using standard widget management:

You must specify your Zillow Web Services ID (ZWS ID), and either a screen name or email from which to load reviews. You can also specify the number of reviews to include, and whether or not to include team member reviews. The widget does some basic data validation. It ensures at least a screen name or email is provided, and is smart enough to call the Zillow API based on the input (basically, if that field has a “@” symbol, it assumes the field contains an e-mail address; otherwise it assumes a screen name). It also makes sure the number of reviews is a valid integer between 3 and 10, and defaults to 3 if an invalid value is provided.

One other performance enhancement I added was the use of the transient API. It allows a developer to store data that is expensive to calculate. In this case, I don’t want to make HTTP calls to Zillow every time a page or post is rendered. Instead, I make the call one and save the results to a transient. This data is set to expire after 24 hours, though WordPress may expire it sooner. Once expired, it will be regenerated the first time it is needed. And since the reviews widget can be embedded multiple times with different settings, each widget has its own transient storage.

When placed inside a widget area, the page output looks something like this:

The formatting will follow your theme styles, but can easily be overridden with custom CSS. All of the fields have CSS classes that should make it very simple to apply your own styles.

What’s Next?

As of this writing, the plugin only does Zillow Reviews. I’m purposefully starting small to let some colleagues and peers review it and make sure I’m not doing anything silly in the code. As I have time I’ll update to use other features of the Zillow API such as listings. I’d also like to add features, such as allowing you to ignore ratings below a certain star count (to filter out the bad reviews) or selecting different fields to display from the raw XML.

And of course, I’ve released this as a totally free plugin and placed the source code on GitHub, so feel free to modify or enhance and submit a pull request. Hope you enjoy!

Down Free Zillow WordPress Plugin

Mike