The following instructions provide further details for users who wish to manually create and use search and display Filters with various Buying Buddy display methods (widgets and links).
REMEMBER! The easiest way to get started creating and using most Filters with Widgets or Custom Search Links, is to use one of the "Widget Wizards" in the Widget area in your Buying Buddy account.
Then choose either "Create a Custom Search Link", or, "Display Properties with Widgets".
The Wizard includes most common filter options. More advanced filter options can be added manually to any filter. These options are described in this reference.
The following notes are for users who wish to understand how to create and edit filters.
Using a Filter
WARNING: Some parameters below are marked "Filter Only" and "Hidden".
If you include "Filter Only" Filter Options with filters on "Search", "Results" or "Map" widgets then these values will be shown as criteria, BUT these are not currently available as editable fields on the search form or modify search panel, i.e. "filter only" options will be maintained if modifying other search criteria, but site visitors will only be able to delete the "filter only" criteria.
"Hidden" filters can set set in Filters, but these are currently -
(a) NOT SHOWN as selected criteria on the modify search panel, and
(b) they will be be CLEARED (i.e. removed) if the 'modify' search option is used.
Browsers will not support filter strings longer than 2048 characters.
I'll help improve the filter syntax documentation to be more structured and professional. Here's a clearer presentation of the rules:
Filter Syntax Rules
Basic Structure
- Field Addition
- Use the plus symbol (+) to add a new field
- Example:
+price_max.....+beds_min
- Value Assignment
- Use the colon symbol (:) to assign values to a field
- Example:
+price_max:500000+beds_min:3
- Multiple Values
- Separate multiple values for a field with commas
- Example:
+status:active,under-contract
- Spacing Rules
- Do not include spaces between operators ( + and : )
- Include spaces only when they are part of a value name
Widget Implementation
Required Format
- Enclose the entire filter criteria in quotation marks
- Place criteria after the equals sign
- Format: filter="criteria"
Example
filter="price_min:500000+city:Lone Tree"
Custom Search Links
Required Format
- Do not enclose filter criteria in quotation marks
- Append filter to the Results Page URL
- Use ? for the first parameter
- Use & if the filter is a subsequent URL parameter
Special Characters
- Replace spaces in values with %20
- Example: "Lone Tree" becomes "Lone%20Tree"
Important Note
When using preset "hidden" options on your results page widget, these options may be removed if the user modifies the search criteria.
Example
https://yoursite.com/properties?filter=+price:500000+city:Lone%20Tree
Sequence of Operations
Filters applied to in the URL will override any filter set in the widget short code.
Consequently, links that include filters to a page with a widget will load the widget and override any filter that may be on the widget itself.
Display Widget Example
In this example, a Search Filter has been added to a List Display Widget.
Search Filter has "city" is the search field (with multiple values), and "agent_id" has been added too:
<div id='MBBv3_FeaturedList' filter='city:littleton,parker,denver+agent_id:12345' ></div>
[mbb_widget id='MBBv3_FeaturedList' filter='city:littleton,parker,denver+agent_id:12345']
Custom Search Link Example
In this example, a Search Filter has been added to the Search Page URL
(note: use the URL of your search results page).
http://www.MySite.com/results?filter=city:littleton,parker,denver+agent_id:12345
Syntax: AND or OR?
Understanding HOW the filters work, will help you to get the results you want! The filter system has rules that define how the filter works.
** Also see below: "f) suffix options: _not, _min, _max"
Broaden your search result using OR
Fields can generally include multiple values by separating each value with a comma. The search query will combine these by using OR logic.
e.g. city:A,B,C - this will find results that match either city=A OR city=B OR city=C.
Narrow your search result using AND
Adding more Fields to the search filter with + uses AND logic.
e.g. city:A+zip:55555+price_min:500000 -this will find results where ALL parameters are true,
i.e. city=A, AND zip=55555 AND the minimum price is 500,000
HINT
Be careful to not add conflicting criteria.
For example, if you specify multiple 'status' and also specify a 'sold date range' - then the 'sold date range' will of course only apply to sold listings - so listings with other status will not match and so will not be included in your result.
Specifying too many parameters will lead to few results.
filter={parameters}
All the following parameters can be combined into a single Filter statement.
If a Filter is not specified for a Display Widget then the Widget will display default listings (see Default Listings below)
- MLS criteria
- Map Filters
- Agent ID
- Buyers Agent
- Office ID
- Pagination controls
- Sort controls
- Price Reduction
- Listing / Sold Date
- Sold Date Range
- Open House
- Operators
- Listing Status
- Layout and Display controls
MLS / IDX data values
Use and combine any FIELD NAMES and VALUES from the IDX data set for your MLS.
The best source for this is the "Create and Use Search Filter" Wizard tool in your Buying Buddy dashboard.
- mls_id:{Buying_Buddy_mls_ID}.
- Other MLS search values
Example
filter="mls_id:denver+city:denver,littleton,parker+price_min:200000+price_max:600000+beds_min:3"
Map Filters
- shapesearch:{LAT, LON values)
A map shape can be applied to any filter. You should use the "Create and Use Search Filter" Wizard tool in your Buying Buddy dashboard to generate the map area filter.
- radius:{center,radius)
The {center} should be specified as a Latitude and Longitude number with a space between (use %20 if in a URL).
E.g.
The radius can be one of the supported values of 0.25, 0.5, 1, 5, 10, 20
OTHER Values are NOT supported
NOTE: Currently, the Wizards do not supply Lat and Lon for this method, so you should use Google Maps or any other tool to get the Lat and Lon values for your center point.
Example:
+radius:39.9546236%20-105.0076269,0.5
MLS Agent ID
Note: filter only - field is not shown on the search form
- agent_id:{MLS_agent_id}
The agent_id(s) can be specified either as a single agent, or a selection of agents. If your MLS also uses agent "team" IDs then this value may also be used in this filter.
The agent_id filter value is matched as follows depending on any specified property status:
- For SOLD properties, agent_id will be matched to:
'listing agent's MLS ID' and 'selling agent's MLS ID'
I.e. using agent_id for sold properties will include properties where the agent represented either side of the transaction. - For active and under-contract properties, agent_id will be matched to:
'listing agent's MLS ID' and 'co-listing agent's MLS ID'
Example
Find all active listings where the listing agent's MLS ID -OR- the co-listing agent's MLS ID is '12345'
filter="agent_id:12345"
Find all sold listings where the listing agent's MLS ID -OR- the selling agent's MLS ID is either '12345, or '02588':
filter="agent_id:12345,02588+listings_status:sold"
Buyer's Agent
Note: filter only - field is not shown on the search form.
- seller_id:{MLS_agent_id}
(NOTE: Only relevant when applied with listing_status:sold (see below))
Show listings where the specified Agent's MLS ID is marked as the Buyer's Agent (often called the Selling Agent) on the MLS SOLD listing data.
The value can be specified either as a single agent's MLS ID, or a selection of agents' MLS IDs.
NOTE: When used with listing_status: sold, the agent_id filter will ALSO include matching seller_id (i.e. using agent_id for sold properties will include properties where the agent represented either side of the transaction).
Example
filter="seller_id:12345"
MLS Office ID
Note: filter only - field is not shown on the search form.
- office_id:{MLS_office_id}
The office_id(s) can be specified to show all listings from one or multiple offices.
The office_id filter value is matched as follows depending on any specified property status:
- For SOLD properties, office_id will be matched to:
'listing office id' and 'selling selling id' - For active and under-contract properties, office_id will be matched to:
'listing office id' and 'colisting office id'
Example
Find all active listings where the office id OR the co-listing office id is: ABC01
filter="office_id:ABC01"
Find all sold listings where the office id OR the selling office id is either 'ABC01' or 'REM01':
filter="office_id:ABC01,REM01+listing_status:sold"
Pagination or Limit
- limit:{number}
The limit option allows you to define how many results to show in the widget. This can be any number.
For example, if you just want 5 properties shown, use: limit:5
NOTE: This option is ignore on the Results widget and Interactive Map widget.
Sort Results By
- order:{option}
The order option lets you choose how to sort the results. Nested sort options can be specified.
The default sort order is ascending, but specify "desc" if you want descending values, otherwise leave blank.
- order:price desc: show highest price first (price descending)
- order:price: show lowest price first (ascending prices)
- order:create_dt desc: show most recently listed Listings first
- order:create_dt: show oldest listings first
- order:openhouse_dt desc: show soonest open house listings first
- order:city: sort by city ascending
- order:city, price desc: sort by city ascending and then by price descending
- order:sold_dt desc: show most recent SOLD listings first. IMPORTANT: only use this filter if we have SOLD in your RETS feed, AND, the filter must be specifying SOLD listings too.
- order:rand(): show random listings
- order:FIELD(agent_id,'123456') desc: sort by an agent's listings (using their Agent ID, replace 123456 with your agent ID!)
Note that the Agent ID is in single quotes when inside the FIELD sort option. - order:FIELD(agent_id,'123456') desc, create_dt desc: sort by an agent's listings (using their Agent ID, replace 123456 with your agent ID!) and then by most recently listed Listings first.
- order:FIELD(agent_id,'123456','654321') desc, create_dt desc: sort by an agent's listings (the two agent IDs are 123456 and 654321 - replace with YOUR agent IDs) and then by most recently listed Listings first.
IMPORTANT! When multiple 'agent_id' are specified you MUST add each id as a comma separated list (no spaces) .. AND.. EACH ID must be enclosed with single quotes (as shown above).
Price Reduction
- price_drop:{number}
Price drop can be used to filter properties that have had a price drop in the specified period.
The value can be from 1 to 30 days.
Example
e.g. Show all properties with a price drop in the last 10 days:
filter="price_drop:10"
Recently Listed / Sold
- create_dt:{integer}
- sold_dt:{integer}
The value should be an integer.
This is the days since the property was added to the database (or days since marked as SOLD). We are unable to show or use the actual "listing" date due to MLS rules (go figure!)
Example for new listings
e.g. Show all properties added to the database in the last 5 days:
filter="create_dt:5"
Example for SOLD listings
e.g. Show all properties marked as SOLD in the last 5 days:
filter="sold_dt:5"
e.g. Show all properties marked as SOLD in the last 6 months:
filter="sold_dt:180"
NOTE: sold_dt is only supported IF your account includes SOLD data.
Distressed / Aged Listings
- create_dt_min:{integer}
The value should be an integer.
This is the minimum number of days since the property was added to the database.
This will find listings that have been listed more than so many days.
Example for listings that have been listed for more than 3 months
e.g. Show all properties added to the database more than 90 days ago
filter="create_dt_min:90"
Sold Date Range
- sold_range_min:yyyy-mm-dd
- sold_range_max:yyyy-mm-dd
These filter options allow you to specify a calendar date range using the "sold date" of sold listings.
The value should be specified EXACTLY as yyyy-mm-dd, as shown.
It is not necessary to specify both.
Example
e.g. Show all properties sold in 2020:
filter="sold_range_min:2020-01-01+sold_range_max:2020-12-31"
e.g. Show all properties sold since Jan 1 2020:
filter="sold_range_min:2020-01-01"
NOTE: This is only supported IF your account includes SOLD data.
Open House
- filter="openhouse_dt:{value} (where available)
{value} can be any of the following:
"tomorrow" - open houses tomorrow)
"weekend" - this weekend
"next-weekend" - next weeked
"7" - next 7 days
"10" - next 10 days
"14" - next 14 days
"30" - next 30 days
Example
filter="openhouse_dt:tomorrow" filter="openhouse_dt:next-weekend" filter="openhouse_dt:14"
The following are all HIDDEN search filter options - i.e. they are not available on the Search Widget or the Modify Search panel.
Suffix Options
- _not
- _min
- _max
Note: filter only - field is not shown on the search form
The three suffix values can be used with nearly all data labels to enhance your filters.
Simply apply the suffix to the label as required.
Example
e.g. Minimum of 3200 sqft (if the label is "sqft)
filter="sqft_min:3200"
e.g. Maximum of 2 garages (if the label is "garages")
filter="garages_max:2"
e.g. Exclude fix ups (if the label is "amenities:fx")
filter="amenities_not:fx"
Listing Status
Note: filter only - field is not shown on the search form.
- listing_status (active, under-contract, sold, active-rental, coming-soon)
If additional property status' are supported in our service for your IDX RETS feed then the property status filter can be used:
- filter="listing_status:{sold | under-contract | active | active-rental}" (the default value is 'active')
Rental Properties (active-rental) are not available in all MLS. To determine if rental properties are being supported, check to see if the For Rent option shows on the search form
Under-contract / Sold: "under-contract" and "sold" can only be used as filter values (if available). They are NOT supported in any SEARCH or MODIFY panel, or on methods that lead to a search or modify option.
Coming Soon: Coming Soon will be included with status 'active' (where available)
These are applied in "filters", the options (where available) are:
- filter="listing_status:active" (will include 'coming-soon' if available)
- filter="listing_status:sold"
- filter="listing_status:under-contract"
- filter="listing_status:active-rental"
- filter="listing_status:coming-soon"
Special Notes for SOLD Properties
- Sold properties will display the 'sold price' if it is available in your RETS feed.
- The field label is sold_price, and for FILTERS use: sold_price_min and sold_price_max
Therefore, a filter might use filter="sold_price_min:300000"
Or, for sort: order:sold_price desc" - In general, SOLD data will only have been collected since the SOLD status was supported for any MLS.
However, we can retrieve all SOLD data for a specific MLS-agent-ID, or MLS-office ID.
Please contact us via the Help Desk to request this with details of your MLS-agent-ID or MLS-office-ID.
Special Display Parameters
Note: filter only - field is not shown on the search form.
(a) Only show properties that have photos.
This option is a good filter to use on home page "featured listings" for example, where first impressions are important.
- prop_img:true
(b) Applies to Gallery Display and List Display widgets only.
Hide an entire section on your web page (e.g. <div class="myownlistings">) if there are no listings.
This filter is especially useful where you want to display your own listings but want to hide the widget and any heading if there are NO listings.
Without this option, if there are no listings, then your website could well be displaying a panel such as "See My Listings!" ... and below this it would show "0 listings" from the widget.
- nolistingshide:{html-class}
See instructions for List Display and Gallery Display.
(b) Several special parameters that are only relevant to certain uses:
- Gallery Display Widget: This has extra parameters for carousel and columns.
- Account Panel widget: This has extra parameters to control the layout
Examples of Filters
Example-1
Show listings with a Display Widget.
<div id="MBBv3_FeaturedList" filter="city:denver"></div>
[mbb_widget id="MBBv3_FeaturedList" filter="city:denver"]
Example-2
Show listings with a Display Widget with "limit" and "order" also defined.
<div id="MBBv3_FeaturedList" filter="city:denver+limit:10+order:price desc"></div>
[mbb_widget id="MBBv3_FeaturedList" filter="city:denver+limit:10+order:price desc"]
Example-3
Show listings from my office (office_id=AB), but show 'my' listings (agent_id=1234) at the top, and sort by the most recent listings first.
<div id="MBBv3_FeaturedList" filter="office_id:AB+order:FIELD(agent_id,'1234') desc, create_dt desc+limit:5"></div>
[mbb_widget id="MBBv3_FeaturedList" filter="office_id:AB+order:FIELD(agent_id,'1234') desc, create_dt desc+limit:5"]
Example-4
Show SOLD listings with a Display Widget that are in city of Denver and sold within the last 21 days, with most recent sold shown first:
<div id="MBBv3_FeaturedList" filter="city:denver+listing_status:sold+sold_dt:21+order:sold_dt desc"></div>
[mbb_widget id="MBBv3_FeaturedList" filter="city:denver+listing_status:sold+sold_dt:21+order:sold_dt desc"]
Deprecated Methods
As of May 2017 the the following two separate parameters and now included as values in the filter itself. These methods are depreciated and are no longer supported but do still work until further notice.
limit="{number}"
The limit option allows you to define how many results to show in the widget.
order="{field_name (desc)}"
The order option lets you choose how to sort the results.