Knowledge Base & Support Center

Cloud IDX Real-Time API

Using the Cloud IDX Real-Time API

The Cloud IDX Real-Time API offers on-demand retrieval of IDX property listing data (active listings only) from an iHomefinder server. The API is a RESTful web service comprising several methods for querying and retrieving listing data. 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're also responsible for using and displaying listing data in a manner 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 the methods supported by the Cloud IDX Real-Time API. You can download sample PHP client code for testing the API. (Note, you will need an API account to use this sample code; contact us for a test account if you don't already have one.)

API Entry Point

The only published URL to the API is for the login method. The URLs for all other methods are retrieved from the login response. This enables different API users to be served from different servers for performance purposes, and for the API service to evolve and be migrated to different platforms as required.

The entry point login URL is:

https://www.idxhome.com/restServices/cloud-idx/login

The following parameters must be submitted to the login method using a HTTP POST request:

clientId
password

Parsing JSON Responses

All requests to the Cloud IDX API return JSON-formatted responses. Links to additional API methods (also called resources) are included in these JSON responses using the following format:

"links":[
     {
        "rel":"[resourceName]",
        "href":"http://www.idxhome.com/restServices/cloud-idx/..."
     }
  ]

Since these embedded URLs are subject to change over time — and also contain an authentication token that is only valid for 5 minutes from the initial login — they should always be dynamically pulled rather than hard-coded in your client code.

Login Method

The links section in the login JSON response contains URLs for all methods available in version 1.0 of the CloudIDX Real-Time API. As of this writing, this includes search, detail, cities, and zips methods. All of these methods can be accessed using HTTP GET requests, although some require additional URL parameters. See each method section below for example JSON responses and more information.

The login response also includes two profiles that follow the method URLs: cloudIdxSearchProfile and cloudIdxDetailProfile. The cloudIdxSearchProfile profile defines the search parameters, and example values, that may be included with the search method. The cloudIdxDetailProfile defines the detail listing parameters, and example values, that may be included with the detail method. In both cases, these parameters should be included as URL parameters on the corresponding method URL.

Return Data (Successful Login)

{
  "links":[
     {
        "rel":"search",
        "href":"http://www.idxhome.com/restServices/cloud-idx/client/2/listing-search/MTM4NDMwMDg2MTA3ODoxYjExMWVhNDVlYWVmMjdiOTZhNTE5NjBhMjU3YzYzMzNhZmI0MzkwODk2MmExY2U0NU0ZjFiOGE3YzFhMTU4MjYxNjNlZjNhYjF-hZWFmNDI2ZWE3NmQwMjE4ODdjNmMzNGQxZmIxYTE4MGQ2MjUyM2YZWNhYjAwM2Q5MWFmNzgyYzM3NzcwYzFmNDk5OGM1Y2ExNDZhYjQwMDk2OWI4NmFhYTllZj..."
     },
     {
        "rel":"detail",
        "href":"http://www.idxhome.com/restServices/cloud-idx/client/2/listing-search/MTM4NDMwMDg2MTA3ODoxYjExMWVhNDVlYWVmMjdiOTZhNTE5NjBhMjU3YzYzMzNhZmI0MzkwODk2MmExY2U0NU0ZjFiOGE3YzFhMTU4MjYxNjNlZjNhYjF-hZWFmNDI2ZWE3NmQwMjE4ODdjNmMzNGQxZmIxYTE4MGQ2MjUyM2YZWNhYjAwM2Q5MWFmNzgyYzM3NzcwYzFmNDk5OGM1Y2ExNDZhYjQwMDk2OWI4NmFhYTllZj..."
     },
     {
        "rel":"cities",
        "href":"http://www.idxhome.com/restServices/cloud-idx/client/2/listing-search/MTM4NDMwMDg2MTA3ODoxYjExMWVhNDVlYWVmMjdiOTZhNTE5NjBhMjU3YzYzMzNhZmI0MzkwODk2MmExY2U0NU0ZjFiOGE3YzFhMTU4MjYxNjNlZjNhYjF-hZWFmNDI2ZWE3NmQwMjE4ODdjNmMzNGQxZmIxYTE4MGQ2MjUyM2YZWNhYjAwM2Q5MWFmNzgyYzM3NzcwYzFmNDk5OGM1Y2ExNDZhYjQwMDk2OWI4NmFhYTllZj..."
     },
     {
        "rel":"zips",
        "href":"http://www.idxhome.com/restServices/cloud-idx/client/2/listing-search/MTM4NDMwMDg2MTA3ODoxYjExMWVhNDVlYWVmMjdiOTZhNTE5NjBhMjU3YzYzMzNhZmI0MzkwODk2MmExY2U0NU0ZjFiOGE3YzFhMTU4MjYxNjNlZjNhYjF-hZWFmNDI2ZWE3NmQwMjE4ODdjNmMzNGQxZmIxYTE4MGQ2MjUyM2YZWNhYjAwM2Q5MWFmNzgyYzM3NzcwYzFmNDk5OGM1Y2ExNDZhYjQwMDk2OWI4NmFhYTllZj..."
     }
  ],
  "cloudIdxSearchProfile":{
     "bedrooms":2,
     "cityId":"274,284",
     "fullBaths":1,
     "lotAcres":0,
     "maxListPrice":1000000,
     "minListPrice":0,
     "newConstructionYn":false,
     "openHomesOnlyYn":false,
     "propertyType":"SFR,CND",
     "squareFeet":0,
     "zip":"94702,94703"
  },
  "cloudIdxDetailProfile":{
     "listingNumber":"88873733",
     "boardId":6
  },
  "message":"Include 'idxCloudSearchProfile' url parameters with requests to the 'search' URL. For 'detail' requests, include 'idxCloudDetailProfile' url parameters."
}

Return Data (Failed Login)

{
  "links":[
     {
        "rel":"login",
        "href":"http://www.idxhome.com/restServices/cloud-idx/login"
     }
  ],
  "cloudIdxSearchProfile":null,
  "cloudIdxDetailProfile":null,
  "message":"Client authentication failed."
}

Cities Method

The cities method can be used to pull cities as configured for a particular user. Only the fieldValue values are necessary for searching, but the other data here can be used to add a dynamic area selector to a form.

Return Data (Partial)

{
  "links":[

  ],
  "cities":[
     {
        "label":"Acampo",
        "fieldValue":"2",
        "fieldName":"cityId"
     },
     {
        "label":"Alameda",
        "fieldValue":"12",
        "fieldName":"cityId"
     },
     {
        "label":"Alta",
        "fieldValue":"20",
        "fieldName":"cityId"
     },
     
     ...

  ],
  "message":null
}

Zips Method

The zips method can be used to pull zips as configured for a particular user. Only the fieldValue values are necessary for searching, but the other data here can be used to add a dynamic area selector to a form.

Return Data (Partial)

{
  "links":[

  ],
  "zips":[
     {
        "label":"93001",
        "fieldValue":"93001",
        "fieldName":"zip"
     },
     {
        "label":"93610",
        "fieldValue":"93610",
        "fieldName":"zip"
     },
     {
        "label":"93620",
        "fieldValue":"93620",
        "fieldName":"zip"
     },

     ...

  ],
  "message":null
}

Search Method

The search method can be used to search for IDX listings based on a search profile. The cloudIdxSearchProfile section in the return JSON from the initial login (see above) includes all of the available search parameters. Only basic search criteria are available in version 1.0. At least one geographical URL parameter must be included (e.g., cityId or zip). The results returned provide summary data for each matching listing; this summary data should be suitable for a "thumbnail" type of results display. A maximum of 100 listings are returned.

To narrow the search by one or more cities, use the cityId URL parameter with one or more comma-separated city IDs appended to the end of the search method URL:

?cityId=12,20

To narrow the search by one or more zip codes, use the zip URL parameter with one or more comma-separated zip codes appended to the end of the search method URL:

?zip=93610,93620

Return Data

{
  "links":[

  ],
  "cloudIdxListingSummaryList":[
     {
        "listingNumber":"88873733",
        "propertyTypeLabel":"LL",
        "summaryType":null,
        "statusLabel":"Active",
        "status":"ACTIVE",
        "listPrice":5000000.000000000000,
        "fullBaths":null,
        "halfBaths":null,
        "officeName":"River Ridge Realty",
        "bedrooms":null,
        "photoThumbnailUrl":"http://pix.idxre.com/pix/...",
        "squareFeet":null,
        "lotAcres":20.716000000000,
        "squareFeetRange":null,
        "photoCount":7,
        "boardId":6,
        "propertyTypeOrder":null,
        "ownListing":false,
        "unitTotal":null,
        "addressDisplayType":"FULL_ADDRESS",
        "address":{
           "streetNumber":"10",
           "street":"Main",
           "city":{
              "cityId":null,
              "cityName":"Sacramento",
              "state":"",
              "correctedCityId":null,
              "validForGeocodeYn":null,
              "validPostalCityYn":null,
              "latitude":null,
              "longitude":null,
              "mlsListings":null,
              "neighborhoodSet":null
           },
           "state":"CA ",
           "postalCode":"95837"
        },
        "streetName":"Main",
        "streetNumber":"0",
        "cityName":"Sacramento",
        "state":"CA ",
        "postalCode":"95837",
        "latitude":38.690139,
        "longitude":-121.616900,
        "openYn":null,
        "openDate":null,
        "openTime":null,
        "openDateText":null,
        "squareFeetRangeYn":false,
        "schoolDistrict":null,
        "agentName":"Terrie Hunt",
        "agentPhone":"(916) 555-1212",
        "coAgentName":null,
        "coAgentPhone":null,
        "officePhone":"(916) 555-1213",
        "coOfficeName":null,
        "coOfficePhone":null,
        "agentCode":null,
        "officeCode":null,
        "boardLogo":null,
        "tourUrl":null,
        "brandedVirtualTourUrl":null,
        "basicVirtualTourUrl":null,
        "virtualTourUrl":null,
        "extraUrl":null
     },
     {
        "listingNumber":"88843210",
        "propertyTypeLabel":"LL",
        "summaryType":null,
        "statusLabel":"Active",
        "status":"ACTIVE",
        "listPrice":4586000.000000000000,
        "fullBaths":null,
        "halfBaths":null,
        "officeName":"Western Land Company",
        "bedrooms":null,
        "photoThumbnailUrl":"http://pix.idxre.com/pix/....",
        "squareFeet":null,
        "lotAcres":229.300000000000,
        "squareFeetRange":null,
        "photoCount":1,
        "boardId":6,
        "propertyTypeOrder":null,
        "ownListing":false,
        "unitTotal":null,
        "addressDisplayType":"FULL_ADDRESS",
        "address":{
           "streetNumber":"20",
           "street":"Walnut",
           "city":{
              "cityId":null,
              "cityName":"Sacramento",
              "state":"",
              "correctedCityId":null,
              "validForGeocodeYn":null,
              "validPostalCityYn":null,
              "latitude":null,
              "longitude":null,
              "mlsListings":null,
              "neighborhoodSet":null
           },
           "state":"CA ",
           "postalCode":"95742"
        },
        "streetName":"Walnut",
        "streetNumber":"20",
        "cityName":"Sacramento",
        "state":"CA ",
        "postalCode":"95742",
        "latitude":38.596002,
        "longitude":-121.212646,
        "openYn":null,
        "openDate":null,
        "openTime":null,
        "openDateText":null,
        "squareFeetRangeYn":false,
        "schoolDistrict":null,
        "agentName":"Forest W. Halford",
        "agentPhone":"(916) 555-1212",
        "coAgentName":null,
        "coAgentPhone":null,
        "officePhone":"(916) 555-1213",
        "coOfficeName":null,
        "coOfficePhone":null,
        "agentCode":null,
        "officeCode":null,
        "boardLogo":null,
        "tourUrl":null,
        "brandedVirtualTourUrl":null,
        "basicVirtualTourUrl":null,
        "virtualTourUrl":null,
        "extraUrl":null
     }
  ],
  "message":null
}

Detail Method

The detail method can be used to retrieve detailed information and all listing photos for a single IDX listing. The cloudIdxDetailProfile section in the return JSON from the initial login includes the required URL parameters (listingNumber and boardId). These parameters should be added to the end of the "detail" resource url, for example:

?listingNumber=88873733&boardId=6

Return Data

{
  "links":[

  ],
  "cloudIdxListingDetail":{
     "listingNumber":"88873733",
     "listingStatusDisplay":"For Sale",
     "listPrice":5000000.000000000000,
     "fullBaths":null,
     "halfBaths":null,
     "officeName":"River Ridge Realty",
     "bedrooms":null,
     "photoThumbnailUrl":"http://pix.idxre.com/pix/...",
     "squareFeet":null,
     "lotAcres":20.716000000000,
     "mlsPhotoCount":3,
     "boardId":6,
     "unitTotal":null,
     "address":{
        "streetNumber":"10",
        "street":"Main",
        "city":{
           "cityId":798,
           "cityName":"Sacramento",
           "state":"",
           "correctedCityId":null,
           "validForGeocodeYn":null,
           "validPostalCityYn":null,
           "latitude":null,
           "longitude":null,
           "mlsListings":null,
           "neighborhoodSet":null
        },
        "state":"CA ",
        "postalCode":"95837"
     },
     "streetName":"Main",
     "streetNumber":"10",
     "city":"Sacramento",
     "state":"CA ",
     "postalCode":"95837",
     "latitude":null,
     "longitude":null,
     "openDate":null,
     "openTime":null,
     "schoolDistrict":null,
     "agentName":"Terrie Hunt",
     "agentPhone":"(916) 555-1212",
     "coAgentName":null,
     "coAgentPhone":null,
     "officePhone":"(916) 555-1213",
     "coOfficeName":null,
     "coOfficePhone":null,
     "agentCode":"SHUNTTER",
     "officeCode":"01ABCD",
     "brandedVirtualTourLink":null,
     "virtualTourLink":null,
     "yearBuilt":null,
     "fireplaceYn":null,
     "numFireplaces":null,
     "garYn":null,
     "garageSpaces":null,
     "lotSqFt":902389,
     "poolYn":null,
     "stories":null,
     "viewYn":null,
     "viewDescription":null,
     "style":null,
     "mlsarea":"10837",
     "neighborhood":null,
     "subdivision":null,
     "horsePropertyYn":false,
     "propertySubType2":null,
     "diningRoomYn":null,
     "basementYn":null,
     "waterFrontYn":null,
     "waterfrontDesc":null,
     "waterBody":null,
     "familyRoomYn":null,
     "propertyLocation":"Other-Rmks",
     "newConstructionYn":null,
     "golfCourseYn":null,
     "oneStoryYn":null,
     "fullPartialAddress":"F",
     "unitNumber":null,
     "mlsphotoUrl":null,
     "mlsthumbnailUrl":null,
     "mlsphotoCount":7,
     "county":"Sacramento",
     "assocId":null,
     "region":null,
     "censusTract":"0.00",
     "foreclosureYn":null,
     "reoyn":null,
     "shortSaleYn":null,
     "agedCommunityYn":null,
     "availableForLeaseYn":null,
     "blogPolicy":1,
     "dockYn":null,
     "investmentYn":null,
     "leaseToPurchaseAllowedYn":null,
     "preforeclosureYn":null,
     "rentalPeriod":null,
     "bedroomsAboveGrade":null,
     "bedroomsBelowGrade":null,
     "photos":[
        {
           "id":{
              "listingNumber":"88873733",
              "boardId":6,
              "priority":0
           },
           "photoName":null,
           "fixedPhotoName":"10073733_0.jpg",
           "ihfphotoUrl":"http://pix.idxre.com/pix/...",
           "ihfthumbnailUrl":"http://pix.idxre.com/pix/...",
           "firstReceivedDate":1284752612697,
           "updatedDate":1342201152307,
           "deleteDate":null,
           "photoTempId":531730089,
           "ihffullPhotoUrl":"http://c3418431.r31.cf0.rackcdn.com/...",
           "boardId":6,
           "listingNumber":"88873733"
        },
        {
           "id":{
              "listingNumber":"88873733",
              "boardId":6,
              "priority":1
           },
           "photoName":null,
           "fixedPhotoName":"10073733_1.jpg",
           "ihfphotoUrl":"http://pix.idxre.com/pix/...",
           "ihfthumbnailUrl":"http://pix.idxre.com/pix/...",
           "firstReceivedDate":1284752612697,
           "updatedDate":1342201152307,
           "deleteDate":null,
           "photoTempId":531730090,
           "ihffullPhotoUrl":"http://c3418431.r31.cf0.rackcdn.com/...",
           "boardId":6,
           "listingNumber":"88873733"
        },

        ...

     ]
  },
  "message":null
}

Additional Notes

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 support@ihomefinder.com 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?