Page Text: The subject property latitude. If not defined, we'll geo-code the subject property address.
geo_lon (Optional)
The subject property longitude. If not defined, we'll geo-code the subject property address.
sqft (Optional)
Square feet of the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
beds (Optional)
Number of bedrooms in the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
baths (Optional)
Number of bathrooms in the subject property, which helps find accurate comparables and appears in the Homebeat as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
garages (Optional)
Number of garage spaces in the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
lot_size (Optional)
Lot size in square feet of the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
taxes (Optional)
Yearly tax amount of the subject property, which appears in the Homebeat report as a comparable feature. If not defined, we will try to establish this based on tax parcel data.
name (Optional)
The leads full name. Appears on the Homebeat and in update emails.
email_address (Optional)
The leads email address. If defined, we will use this to send Homebeat welcome email and Homebeat updates based on the defined frequency.
phone (Optional)
The leads phone number.
This API call mimics what happens when a user creates a new Homebeat in the Cloud CMA UI. The parameters above match the fields in our new Homebeat form. Upon the creation of a new Homebeat, we will send a welcome email, followed immediately by the first Homebeat update, to the leads email address if that was provided.
Any errors in this request will return a 4xx http status code and JSON with an error message in an error attribute.
Error Example
{ "error": "No matching listings were found on the MLS." }
Common errors:
"You need to sign in or sign up before continuing." because api_key param is missing.
"This user does not have the Homebeat feature." because this user does not have the Homebeat add-on.
"No matching listings were found on the MLS." happens when you provide a subject property address that is outside the current MLSs operating boundary. Example the user is part of an MLS in California, but the subject property address is in Florida.
"Frequency is not a valid option." because of a bad value for the frequency attribute.
Homebeat Report
You can download a report of all your Homebeats, along with current view counts, in either CSV or JSON format.
Get report
get
https://cloudcma.com/homebeats/report?api_key=your-api-key
Set the Accept header to text/csvor application/json and you'll get back a response body that contains data about all created Homebeats in the requested format. Alternatively, you can make your get request to reports.csv or reports.json to force the format returned.
If the api_key param is not included, you'll get data back for the currently logged in user.
MLS Security Methods
Cloud CMA allows real estate agents to easily create custom CMA, Buyer Tour, and Property Reports. It utilizes the best sources of property, school, neighborhood, and other information it can find on the internet to create these reports. The best source of listing data is the MLS, so it interfaces with the MLSs RETS server to acquire listing data for sold, pending, expired, and active properties.
We handle MLS data aggregation in two ways:
Ad hoc queries
Using this method we query the MLSs RETS server only at the time the user requests a report to be created. Users are typically only requesting 10-30 listings per CMA or Buyer Tour, and only one listing per Property Report, so these queries are very small and efficient.
Traditional data duplication
We aggregate a subset of the MLS database and synchronize the listing data at set intervals.
Since MLS listing data can only be accessed by licensed members of the MLS, Cloud CMA utilizes one of the following three security methods to ensure that only valid, active members have access.
Method 1
When a new user sets up their profile in Cloud CMA, they are asked to choose their MLS, then they are prompted for their MLS credentials. The MLS password is stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we use their MLS credentials to log into the RETS server. If the users MLS credentials are invalid, the login to the RETS server will fail, and the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from the RETS server without the proper credentials.
Pro:
The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.
Con:
The MLS may not have RETS credentials set up for each and every member. Many MLSs manually set up RETS credentials on an as needed basis, so each member may not already have RETS access.
Method 2
The MLS provides us (W+R Studios) with specific RETS credentials and instructs us to use those every time we query the RETS server for all of our users. When a new user sets up their profile in Cloud CMA, they are still asked to choose their MLS, then they are prompted for their MLS credentials. The MLS credentials are stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we use our MLS credentials to log into the RETS server. Upon successful login, we query the Agent or User table of the RETS server with the agents id and password, then look at the resulting data to make sure this user exists and is an active member. If our query returns no results or an indication that the member is no longer active, the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from the RETS server without the proper credentials.
Pro:
The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.
Con:
The MLS may not allow querying on the password field in the Agent table, or may not return that field in the dataset for use in a post query comparison. As a less secure alternative, it's possible to query the Agent table for the id and an indication that this user is an active member, essentially ignoring the password.
Method 3
We offer two 'Single Sign On' methods, which are especially good for MLSs that have a site license where every member has free access to Cloud CMA. In this scenario, users cannot log in directly at cloudcma.com, but instead must first log into their MLS system and click on a button or link to access Cloud CMA.
We have our own 'homebrew' form of SSO where parameters are passed in the url - the MLS code, the users id, a secure hash, and a timestamp. Details of this algorithm can be provided on request. We have several MLSs using this method, it works well, and it's simple to implement.
We also support the SAML standard for SSO and are currently SAML certified with one of the major MLS vendors. We are set up to easily add other SAML providers.
SSO works especially well when the MLS implements the API for passing listing numbers to automatically create reports for listings the user has currently selected. This allows for a deep integration between MLS system and Cloud CMA, requiring no additional login by the user and making it seem like one seamless system.
Pro:
The MLS has complete control over this user not only being able to utilize MLS data in Cloud CMA, but even having rights to access Cloud CMA at all. The user can be cut off at any time using the normal deactivation process built into the MLS workflow - if they can't access the MLS system, they can't access Cloud CMA.
Con:
The MLS needs to set up the link to Cloud CMA within the MLS system.
Method 4
When a new user sets up their profile in Cloud CMA, they are still asked to choose their MLS, then they are prompted for their MLS credentials. The MLS credentials are stored in our system using RSA public key encryption, and any time it's transmitted, it is done so in that encrypted form. Whenever the user performs a query for property data, we verify their credentials against our synchronized table of currently active agents to ensure they are an active member. If our query returns no results or an indication that the member is no longer active, the corresponding error message will be relayed to the user. The user can then check their credentials and try again, but they will never successfully get listing data from us without the proper credentials.
Pro:
The MLS has complete control over this user being able to utilize MLS data in Cloud CMA, and the user can be cut off at any time using the normal deactivation process built into the MLS workflow.
Cloud CMA RETS Queries
Cloud CMA allows agents to create CMA, Buyer Tour, and Property reports. We DO NOT download the entire MLS and keep it synced in servers on our site. The agents enter criteria and we do real-time RETS searches to download data from the MLS at that moment in time.
We basically do three types of searches in Cloud CMA:
Mls nums search - single or multiple mls nums at a time. Very straightforward, simple search.
Address search - usually we have to break an address down into street num, street name, city, state, zip and do the search. Also very straightforward.
Lat/Lon range search - basically a Latitude range and a Longitude range forming a rectangular proximity search area around a given subject property. This is a more complex query, and I've seen it trip up RETS servers in two ways:
The latitude and longitude fields on some servers are not indexed, even though these are simple decimal values and are very useful search fields.
Because the longitude in the US is a negative number, to search a range you end up with this funky double negative DMQL syntax that looks like this:
(LONGITUDE=-92.590--92.588),(LATITUDE=44.866-44.868)
That can break the parser on some RETS servers. We have come up with a fairly simple way around this on RETS servers in the past. Assuming that the RETS parser is simply querying a View in your database, create a new field called "ABSLONGITUDE" in your View which contains the absolute value of the longitude. On our side, we just set a flag to query that new field instead and the query above becomes:
(ABSLONGITUDE=92.588-92.590),(LATITUDE=44.866-44.868)
That works for us and is typically pretty easy to implement on the server side.
This method of real-time searches is more secure, since we do not have all the MLS data replicated on our servers, and provides less load on the RETS server, since we are only searching an extremely small subset of the MLS daily.