PropertyHub Real Estate API

The PropertyHub Real Estate API is the most effective way to get real estate data from the Zoo system on an on demand basis. For ongoing property data updates we still recommend using REAXML where possible, however it does not cover many forms of data we store and isn’t practical in some situations.

To interactively try out the API you can use the API Explorer which lets you test queries in browser and contains more specific documentation about supported fields.

Overview

The API is implemented using simple REST principles.  GET requests will always retrieve data where as POST requests will always create or update data.

The API supports data both in and out of the system as either JSON or XML. With both forms, all the fields are identical. The JSON format is recommended and is often easiest to use.

You can specify the desired output format either in the URL (e.g. /properties.json or /properties.xml) or via the Accept: HTTP header. Without any specific format specified, JSON will be used.

Note:If you open an API URL in a browser with no format specified, the browser may send Accept: application/xml which may confuse you if you were expecting JSON

All search results will return a standard format for all data types (Properties, Agents, etc…) which includes the page number, total number of results and the number of results returned with the current request. This allows for code re-use.

Operators

Many of the parameters for the API support different operators to request information more flexibly than an exact match.

Lists

Particularly for ID’s, you can specify multiple values separated by commas. The API specification will specify which fields this applies to.

Ranges,  Not equal and Between

The following operators are supported for many fields:

Operator Notes Example
= Exact match. Default for all fields  cars=2
~ Case insensitive match  xml_id=~AbCdEf
 > Greater than  updated_at=>2014-06-01
 < Less than  beds=<5
 ! Not equal to  status=!1
 / Between two values. Separate the values by a comma.  price=/200000,300000

 

Dates

Some fields such as created_at, updated_at and sold_date support dates when searching. You may specify a date/time in many different formats, including YYYY-MM-DD HH:MM:SS or Unix Timestamps.

Other formats including “Yesterday” and “-1 week” will work, however it is recommended that an exact unambiguous date/time is specified.

Dates can use some of the operators above including greater than and less than.

All dates and times use the Sydney timezone, which includes Daylight Savings.

Caching

To reduce the amount of data transferred, there are two different ways to minimise the amount of data sent.

Always search with updated_at where possible. If you are only interested in new or changed data then this will prevent any duplicate or unchanged data from being sent.

The API will also send a Etag header. This is a hash of the data which can be used to let your App know if it has changed or not.

If you store the returned data from the API with the Etag value, on subsequent hits for the same query you can send a If-None-Match header with the Etag value. If the data has not changed then you will get a 304 Not Modified response and the data will not be re-sent. If the data has changed then it will be sent normally so you can update your cache.

Caching is important but not always applicable in all situations. If you wish to discuss the best way to store or cache data from our API for your application, please contact us and we will be able to advise you.

No data from our API is cached, you will always get live and up to date data if you require it.

Properties API

The Properties API can return a lot of information so it is important to minimise redundant data transmission.

When searching for properties, the full property information is not returned, only a single image is returned and some extra information is left off. It should be enough information to show a property search results page without having to do any further API calls.

If no actual property data is required, summary=1 can be sent which will only send ID’s and dates. Useful for looking up xml id’s from Zoo property ids without retrieving much information.

If looking for new property information, it is a good idea to search by greater than updated_at to only retrieve data which has changed.

Property Types

The types attribute can have the following values:

  • ResidentialSale
  • ResidentialLease
  • HolidayLease
  • NewDevelopment
  • Commercial
  • BusinessSale
  • ProjectSale

Property Statuses

1 – Current
2 – Sold
3 – Leased
4 – Withdrawn
5 – Under Offer
6 – Draft
7 – Off Market (treat the same as Withdrawn)

Property Price Per

This is for the rental period of for lease properties.

0 – Monthly
1 – Weekly
2 – Quarterly
3 – Yearly

Custom Fields

Custom fields (Found on the Extras tab in Zoo) can be accessed from the custom array when requesting a property.

Custom values can also be searched by using the syntax &custom.field_name=xyz. The field currently can not be set from the Zoo interface so please contact us and we will assist you.

All the regular operators will work on custom fields.

Further Information

Please direct any questions to helpdesk@agentpoint.com.au so we can assist you.