Cloud IDX Bulk Data API
Using the Cloud IDX Bulk Data API
The Cloud IDX Bulk Data API provides access to iHomefinder's aggregated and standardized listing data from one or more MLS® Systems. Listing data is made available via a SOAP/RPC web services interface. In order to use the API you'll need to have an API account with iHomefinder and be approved for IDX by your MLS® System operator. You are also responsible for using and displaying listing data in a manner that is compliant with your MLS® System's IDX rules. Please note, Cloud IDX is only available for use by an active member of an MLS® System, subject to MLS® System approval.
This page describes how your client-side application should use the methods supported by the Cloud IDX Bulk Data API. For additional details refer to the specification for the Bulk Data API methods. You may also download sample PHP client code for testing the API. (Note, you will need login credentials for a test account to use this sample client code. Contact us for a test login if you don't already have an account.)
To understand the listing data provided by the API please refer the data dictionary.
Accessing the Cloud IDX Bulk Data API
The complete WSDL specification for the Bulk Data API is available at the following URL:
To access listing data you will need to call the
login method to begin a web services session. The exact syntax required to make the
login call will depend upon your client-side implementation language. However, in general, you will first create a SOAP client interface using the above URL as a parameter. Then, you will call the
login method on the SOAP client interface using your API account username and password as parameters. The return value from a successful
login will be a "context ID" (an integer) for your web services session. The context ID will be required for all subsequent SOAP method calls in the session.
Once you've logged in, over a dozen API methods are available, enabling you to retrieve listing data, open homes information, listing photos, and MLS board information.
Retrieving Your Initial Listing Data Set
During your development process you should get the identifiers for your MLS® board(s) using the
getBoards method. This returns an array of integers, each specifying one of your authorized boards. You should then download the compliance data for your board(s) using the
getBoardData method. This compliance data describes rules and other information that must be used in displaying listing data in conformance with an MLS® Systems's IDX regulations.
Next, you should get the listing data field headers for your board(s) using the
getHeaders method. This data describes each field in a listing, such as listing number, street address, price, etc.
You are then ready to do a complete a complete download of all listing data from your board(s) using the
getAllListings method. We recommend you initially issue a
getAllListings request to get the first 1000 listings, and then subsequently use
getListingsSince to retrieve the remaining listings. Repeated calls to
getListingsSince will return additional subsets of 1000 listings. If you omit the
sinceDate argument, then our system will automatically advance it for you. You should stop after you've received less than 1000 listings on a request.
The data fields in each listing are in CSV format, and all listings are wrapped in XML. Many web programming languages have convenient libraries for handling XML and CSV data. For example, in PHP we recommend using SimpleXML to parse XML responses, and str_getcsv() to parse CSV data.
Listing photos are supplied as hosted URLs and need to be retrieved separately from the listing data downloaded with the
getListingsSince methods. We recommend using the
getPhotosForMultipleListings method, in reasonably-sized batches, to retrieve photo URLs encapsulated in XML for all listings that you download (including both new listings and modified listings).
Updating Your Listing Data Set
Once you have downloaded the initial full set of listings, you can make periodic calls to the
getListingsSince method to refresh your data. Note that the
sinceDate parameter is optional; if not supplied we will return all the new and changed listings since your last download. If you do wish to provide a
sinceDate argument, it must be supplied as a string parameter in the form:
YYYY-MM-DD HH:mm:SS sss GMT, where
YYYY – 4 digit year
MM – 2 digit month (01-12)
DD – 2 digit day of month (01-31)
HH – 2 digit 24-hour hour of day (00-23)
mm – 2 digit minute of hour (00-59)
SS – 2 digit second of minute (00-59)
sss – 3 digit millisecond of second (000-999)
GMT – all times represented in Greenwich Mean Time
iHomefinder updates our own data every two hours in most boards. We recommend you do your updates at the same frequency, or less often. Make sure to check the
inactiveYN field in each listing; if this field is set to 1, the listing should be considered dropped from the active data set. (Note: two weeks after a listing goes inactive we remove it from the active listings data set. Make sure to update your data at least every two weeks and check the
If you want to refresh your entire data set from time to time, you can reset the
sinceDate timestamp using a
getAllListings method request, and then follow that with a full series of
getListingsSince method requests as described in the previous section. Many of our clients do a complete refresh once a month.
For open homes data (in boards that provide this data), we recommend using the
getOpenHomeInfoForBoard method to retrieve all current open homes in a single request. The
sinceDate argument on
GetOpenHomeInfoForBoard method is optional; if it is omitted, the method will return all open homes for the board on each request (note, the
Context ID and
BoardID arguments are required). We recommend that you do not use the
getOpenHomeInfo method, as it will be deprecated in a future release of the API.
Please note that you should always call the
logoff method when you have completed your session. Your session will timeout after 15 minutes of inactivity if you do not logoff.
Sold listings data is available for some boards. In order to access solds data you will need a second API account and a separate set of login credentials.
You should retrieve solds listings in a manner similar to the procedure described above for active listings. First, do an initial
getAllListings method call to pull the first 1000 listings. Then, do a series of
getListingsSince calls to pull subsequent groups of 1000 listings. Don't use a
sinceDate parameter in this call; we will keep track of where you are in the overall list of sold listings.
Note that there are generally different IDX display rules for solds. For example, you must usually display both the listing and buyer's agents and brokerages. You may not be able to display the listing price. And, you will likely be permitted to only show one photo in order to protect the privacy of the current occupants.
Your code will need determine when you want to "sunset" sold listings and remove them from display. For example, you may only want to display listings that go back six months or one year — sold data becomes less relevant to consumers as it ages since it no longer reflects current market conditions.
Please be aware that the API is not available during our regular weekly maintenance window of Sunday evening at 11:00pm PT through Monday morning at 12:30am PT.
If you experience difficulty logging in, please contact us at firstname.lastname@example.org and provide the IP address from which you are attempting to access the API. We block traffic from certain ranges of IP addresses (such as most Amazon AWS IP addresses) due the prevalence of malicious traffic originating from these sources.
Did you find this article helpful?