Smart Frame API

The Smart Frame API is another tool to help developers customize flexmls IDX for their customer. The Smart Frame API provides the ability to apply listing search parameters to an IDX link.  This allows the use of a single IDX link to create large lists of links for cities, zips, price ranges, and other search criteria.

An IDX link typically looks similar to http://link.flexmls.com/rkrjtu59j3l,6

Using the above link as an example, if the MLS supports a field called Garage Stalls, the following link specifies three garage stalls in the search criteria:

http://link.flexmls.com/rkrjtu59j3l,6&GarageStalls=3

Available Parameters

In order for each parameter to be applied to the search, it must already be enabled within the IDX link. For example, a listing start date will not be applied to the search if the start date is not part of the link parameters, and if the Photos tab is disabled for that link, specifying a photo as the starting point for a link will not work.

Property Types

Parameter name: propertytype

Property types may be specified with the propertytype parameter. This field accepts a comma separated list of property type names. When more than one MLS is searched, the property type names change to generic names rather than those names as customized by the MLS (e.g. “Single Family” may become “Residential” when more than one MLS is chosen). The list of generic names include Residential, MultiFamily, Land, Commercial, Farm, and Rental.

MLSs

Parameter name: mls

If an IDX link allows for a multiple MLS search, specific MLSs may be selected with the &mls= parameter. This parameter accepts a comma separated list of MLS names.

Main List Fields

Parameter name: the field’s name

A main list field may be specified either by its field ID or by its display value with any white space removed. So, if “Begin Date” is that field’s label, a listing’s begin date may be specified by either &begin_date= or &BeginDate=.

Common field IDs include the following: list_price, house_nbr, streetdirprefix, streetaddress, streetsuffix, streetdirsuffix, city, state, zip, total_sqft, yr_built, total_br, total_bath . Not all MLSs use all of these fields, but they should be relatively common across all MLSs and property types. Some example exceptions include bathrooms and bedrooms for commercial or land property types.

Date queries are specified with dates in the form of MM/DD/YYYY. If a date range is desired, the start and end of the range should be separated by a comma; for example, &BeginDate=01/01/2011,12/31/2011 . If only one date is supplied, the search will return results that match that single date.

Example Date Parameter Description
&BeginDate=01/01/2009 a begin date of exactly 01/01/2009
&BeginDate=01/01/2009,06/01/2009 a begin date range from 01/01/2009 to 06/01/2009

Text field queries are specified by the parameter followed by a string, like the following: &streetaddress=Broadway

The characters #.{}|^~[]`+?& should be omitted from the display value.

List items are specified by the values (not the display values) of the scroll fields. Multiple list items should be comma-delimited. For example: &City=Fargo,Moorhead

Numeric field queries may be specified as a single value, as a range, or as upper and lower ranges:

Example Numeric Field Parameter Description
&TotalBathrooms=5 exactly 5 bathrooms
&TotalBathrooms=3,5 a range of 3 to 5 bathrooms
&TotalBathrooms=>3 at least three bathrooms
&TotalBathrooms=<3 at least one, but no more than three

Detail Fields

Parameter name: the field’s name

Detail fields may only be referenced by their display values, with any white space removed. Parameters are case sensitive. As with main list fields, the detail field must be a field present in the saved search or the quick search. The detail’s group is not referenced in the parameter; for example, if a detail “Dishwasher” is in the detail group “Appliances”, the detail name is needed but the group name is not.

The characters #.{}|^~[]`+?& should be omitted from the field name.

Examples using the various data types of detail fields are below.

Detail Field Data Type Description Example Parameter
Text fields Parameter must include text to for which to search &CondoName=Waterly
Yes/No fields Possible parameters include Y or N &RentalSignAllowed=Y
List fields Parameters must exactly match the list items. Since a detail list field may only contain a single value, specifying multiple values separated by commas will return listings that match at least one of the specified values. &LakeName=Cormorant,Ottertail
Date fields Parameters follow the same format as main list fields: MM/DD/YYYY . A date range may be specified by including two dates separated by commas. &LeaseExpiration=04/13/2011,04/13/2012
Numeric fields Ranges may be specified by including two numbers separated by a comma. &AssociationFee=100.00,200.00

Photos, Videos, and Documents

Parameter names:

  • videos
  • photos
  • documents

These accept one or two numeric values, corresponding to a single value or a range, respectively. For example, photos=1,10 returns all listings that have anywhere from 1 to 10 photos, inclusive.

Open Houses

Parameter name: openhouse

The openhouse parameter will return listings that have have an open house scheduled within the specified date range. This field may take either a single date, a range of dates, or a single integer value. If a single integer is provided, it will be taken to mean “in the next X days.”

Open House Search Type Example
Show open houses in the next certain number of days &openhouse=5
Show open houses on a specific day &openhouse=05/01/2009
Show open houses within a range of days &openhouse=05/01/2009,05/07/2009

List Numbers

Parameter name: listing

Specific listings may be retrieved by MLS number using the listing parameter. Multiple list numbers may be retrieved by specifying the MLS numbers in a comma-separated list. For example: &listing=09-1234,09-1235

Rental Availability Dates

Parameter name: AvailableDates

This parameter works for MLSs supporting the rental availability calendar. The parameters may be specified for a single date, like this: &AvailableDates=1/1/2010 ; or, for a date range, like this: &AvailableDates=5/12/2010,12/1/2010

My Map Overlays Map Shapes

Parameter name: map_overlays

The shapes created with the “My Map Overlays” tool may be referenced with the &map_overlays= parameter. Multiple overlays may be specified in a comma-separated list of map overlay API keys.

To obtain the map overlay API key of an overlay, follow these steps:

  1. Visit the My Map Overlays menu item in the Preferences menu, and select the overlay containing the desired shape.
  2. Click the desired shape, then click the edit link, as shown below:
  3. Click the “Show API Key” link that appears:
  4. The map overlay API key will appear. Use this as the value for the map_overlays parameter.

Custom Map Shapes

Parameter name:

  • shape : single shape
  • shape_X : multiple shapes

Individual map shapes may be specified with the shape parameter, while multiple map shapes may be specified with shape_X, where X starts at 1 and increments as each shape is added. The types of shapes include circle, box, and polygon, each having its own set of additional parameters.

Circle

shape name: circle

Use of the &shape=circle parameter requires the following additional parameters to be included:

Parameter for Single Shapes Parameter for Multiple Shapes* Description
lon1 lon1_X The longitude of the center of the circle
lat1 lat1_X The latitude of the center of the circle
radius radius_X The radius of the circle, in miles

* When multiple shapes are used, X should be replaced with the same value as the corresponding shape_X value.

Rectangle

shape name: rectangle

Use of the &shape=rectangle parameter requires the following additional parameters to be included:

Parameter for Single Shapes Parameter for Multiple Shapes* Description
lon1 lon1_X The longitude of the upper left corner of the rectangle
lat1 lat1_X The latitude of the upper left corner of the rectangle
lon2 lon2_X The longitude of the lower right corner of the rectangle
lat2 lat2_X The latitude of the lower right corner of the rectangle

* When multiple shapes are used, X should be replaced with the same value as the corresponding shape_X value.

Polygon

shape name: polygon

Use of the &shape=polygon parameter requires the following additional parameters to be included:

Parameter for Single Shapes Parameter for Multiple Shapes* Description
lon1 lon1_X The longitude of the first point in the polygon
lat1 lat1_X The latitude of the first point in the polygon
lon2 lon2_X The longitude of the second point in the polygon
lat2 lat2_X The latitude of the second point in the polygon
lon3 lon3_X The longitude of the third point in the polygon
lat3 lat3_X The latitude of the third point in the polygon
lonY lonY_X The longitude of the Yth point in the polygon
latY latY_X The latitude of the Yth point in the polygon

* When multiple shapes are used, X should be replaced with the same value as the corresponding shape_X value.

Circle around specified address

Parameter name: geo=radius

Instead of supplying map coordinates, an address at which to center a radius search may be specified by including a parameter of &geo=radius. Either geo_state or geo_zip must be provided if geo=radius is used. Only one geo=radius parameter may be used on a link at a time.

Parameter Description
geo_range Radius of the circle in miles. Defaults to 1 mile if not provided.
geo_street Street address of the property, e.g. 101 Main St
geo_city City of the property, e.g. Milwaukee
geo_state State of the property, e.g. WI
geo_zip Zip code of the property, e.g. 53201

Multiple Shapes Example

A URL with multiple shapes might look like:

http://link.flexmls.com/oobouwk4mhi,1&shape_1=circle&lon1_1=-96.885597&lat1_1=46.789445&radius_1=50&shape_2=box&lon1_2=-97.147771&lat1_2=47.057753&lon2_2=-96.730291&lat2_2=46.731181

Starting Tab

Parameter name: start

The starting tab may be specified with the start parameter. Its possible values are: map, details, report, tax, supplement, documents, openhouse, calculator, photos, videos, virtualtour, compare .

Starting Photo

Parameter name: photoX

A starting photo may be specified with the photoX value, where X is the starting photo. Setting this will start the IDX link on the photo tab, with photo number X selected.

History Events (Saved Search Links Only)

Parameter name: listingevent

For saved search links, the following parameters are available to return listings that are part of the search and have the following history events occur within a specified number of hours:

listingevent value Description
new New listings
status Listings that changed status
bom Listings that came back on the market
price Listings with a price change

Also use the listingeventhours parameter to specify the number of hours in the past that the events occurred. This parameter takes an integer value, and if absent or the value is not an integer, will default to 24 hours in the past.

Comments on this entry are closed.