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.
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.