×
Menu
Index
Search
 
   
   
   
 

PlatWidget Filtering API

 
The Filtering API lets you use your own HTML controls and some JavaScript to filter lots and listings within an embedded PlatWidget map. To enable the API, contact us with the URI (e.g. https://example.com) of the website your map will be embedded into. Once access has been enabled, you'll be able to use the API for the functions listed below.
 
 
 

Using the Filtering API

When a PlatWidget map is embedded into your website a platWidgetMaps object is created automatically. When the Filtering API is enabled functions are added to the platWidgetMaps object. Each function requires two parameters; a mapId string and an object holding the specified properties. The mapId is required to direct function calls to the intended map since multiple PlatWidget maps can be embedded into a single webpage. Follow these steps to find the mapId for your map.
 
 

filterMap()

platWidgetMaps.filterMap(mapId:string, filterObj:object);
 
Use this function to filter lots and listings in a map based on floor plan attributes or lot status. You can also load a specified target map into the existing embedded map prior to filtering. This is useful when a master map is initially loaded but you want to filter lots in a map that would be accessed by clicking somewhere within the master map.
 
Example: Basic
This example filters the lots and listings within a map that is currently loaded in an embed. Valid properties that can be included in the filter object are shown below.
 
var mapId = "MP100";
var filterObj = {areaMin: 1500, bedMin: 3};
platWidgetMaps.filterMap(mapId, filterObj);
 
Example: Loading the map to be filtered
To change the target map prior to filtering, you simply add the filterTarget property and a valid mapId to the filter object.
 
var mapId = "MP100"; // Always use the initially loaded map's mapId when calling functions.
var targetMapId = "MP200";
var filterObj = {filterTarget: targetMapID, areaMin: 1500, bedMin: 3};
platWidgetMaps.filterMap(mapId, filterObj);
 
Example: Resetting the filter
Including reset:  true in the filter object will clear the filter and bring all lots and listings back into view on the map. All other properties included in the filter object, except for the filterTarget property, will be ignored.
 
var mapId = "MP100";
var filterObj = {reset: true};
platWidgetMaps.filterMap(mapId, filterObj);
 
Valid Filter Object Properties
Below is a list of valid properties that can be included in the filter object.
 
Property
Type
Description
filterTarget   
string
When the filterTarget property is set to a valid mapId, the target map will be loaded into the embed prior to the filter properties being either set or reset.
reset
boolean
Setting the reset property to true will override all other filter properties and reset the map filter. If set to false or emitted entirely it will have no effect.
areaMin
number
The minimum living area required to be included in the filtered result.
areaMax
number
The maximum living area required to be included in the filtered result.
type
string
A case-sensitive match for the property type of lots to be included in the filtered result. If the label used in your own filter does not match the Property Type label that is setup in PlatWidget, you can use the setFilterOptions function to match PlatWidget's filters to your own.
builders
string
A case-sensitive match for the builder name associated with lots to be included in the filtered result. If the name used in your own filter does not match the builder name that is setup in PlatWidget, you can use the setFilterOptions function to match PlatWidget's filters to your own.
bathMin
number
The minimum number of baths required to be included in the filtered result.
bathMax
number
The maximum number of baths required to be included in the filtered result.
bedMin
number
The minimum number of beds required to be included in the filtered result.
bedMax
number
The maximum number of beds required to be included in the filtered result.
floors
number
The exact number of floors required to be included in the filtered result.
garage
number
The minimum number of garage spaces required to be included in the filtered result.
lotSizeMin
number
The minimum lot size required to be included in the filtered result.
lotSizeMax
number
The maximum lot size required to be included in the filtered result.
priceMin
number
The minimum price required to be included in the filtered result.
priceMax
number
The maximum price required to be included in the filtered result.
status
number
Use a status tag number to filter out all lots that do not have a given status tag. Status tags are setup by the account admin. A list of currently used status tags with their corresponding id number can be viewed from the Admin console.
 
 
 

setFilterOptions()

platWidgetMaps.setFilterOptions(mapId:string, filterOptions:object);
 
Use this function to replace the filter options shown on an embedded map's filter tab with options that match your custom filter. Filter options are created dynamically in PlatWidget to match the ranges found in the available lots at load time. For example, if the minumum number of bedrooms offered by the available lots is 3 and the maximum number is 4, the selectable range for bedrooms will be 3-4. In the same manor, if bedrooms are not listed on any lot, the bedroom filter selectors will not be visible. The setFilterOptions function is called for each filter you would like to change. Filter option changes are persistent so they only need to be set the first time a map is loaded. They will still be present after navigating to another map and back again.
 
As with the filterMap function, you can load a specified target map into the embed prior to setting the filter options. This is useful when a master map is initially loaded but you want to set filter options for a map that would be accessed by clicking somewhere within the master map.
 
Example: Basic
This example sets the filter options for a map that is currently loaded in an embed. Let's say a builder's name is setup in PlatWidget as "Example Builder LLC", but you would rather get rid of the "LLC" in your custom filter. You can change PlatWidget's filter option to read "Example Builder" while still using "Example Builder LLC" for the option's value attribute.
 
var mapId = "MP100";
var filterOptions = {
    filterName: "builders",
    options: {
        "Example Builder": "Example Builder LLC",
        "Another Builder 1": "Another Builder 1",
        "Another Builder 2": "Another Builder 2",
        "Another Builder 3": "Another Builder 3"
    }
};
platWidgetMaps.setFilterOptions(mapId, filterOptions);
 
Example: Loading a map prior to setting filter options
To change the target map prior making changes, you simply add the filterTarget property and a valid mapId to the filter options object.
 
var mapId = "MP100"; // Always use the initially loaded map's mapId when calling functions.
var targetMapId = "MP200";
var filterOptions = {
    filterTarget: targetMapId,
    filterName: "bedMax",
    options: {
        "1 Bedroom": 1,
        "2 Bedrooms": 2,
        "3 Bedrooms": 3,
        "4 Bedrooms": 4
    }
};
platWidgetMaps.setFilterOptions(mapId, filterOptions);
 
Valid Filter Option Properties
Below is a list of valid properties that can be included in the filter options object.
 
Property
Type
Description
filterTarget   
string
When the filterTarget property is set to a valid map id, the target map will be loaded into the embed prior to the filter options being set.
skipLoadTarget
boolean
Add this property with a value of true to skip loading the target map when setting filter options. This allows for setting filter options in a child map while keeping the parent or master map loaded.
filterName
string
The filterName property is used to identify which filter will receive the included options. Valid filterName strings are listed below.
options
object
Holds the options and values that will be set. Format as follows: {"Option 1": value, "Option 2": value}
 
Valid filterName Strings
Below is a list of valid filterName strings and the value type expected to go with it.
 
FilterName
Value Type
areaMin
number
areaMax
number
type
string
builders
string
bathMin
number
bathMax
number
bedMin
number
bedMax
number
floors
number
garage
number
lotSizeMin
number
lotSizeMax
number
priceMin
number
priceMax
number