ListingWare API
Learn better by seeing examples? Impatient? Check out sample code at the bottom of this page.
We now also have Widget Code Generators for current customers!
Just sign in at the top-right and click on the IDX Search option in the top menu.
At the bottom of that page you can find these new options. Schweet!
Due to popular demand, we have created the ListingWare Application Programming Interface (API). Using this method, you can create your own custom searches, listing displays, or links directly into ListingWare.
|
ListingWare API | 4/25/2007; 1 hour, 18 minutes; 130 MB: This webinar goes in-depth on the API and how you can customize your service with it. Sound quality is pretty good. Shows older version of our website and our service, but all API info is the same. We were trying out a service from Skype called Skypecast for broadcasting the audio online - there is one hitch toward the end that shows they still had some bugs in the privacy area, so please forgive that. May require the GoToMeeting Codec. |
Where Do I Start?
Everything is built on your base URL - the address that identifies your account. It is in the form of:http://membername.servicename.com/search/ (you received this when the account was created)
If you're using our Complete Website option and have a domain name assigned on your account, you could use:
http://www.yourname.com/search/ (this is only if WE are hosting your domain here)
This is what you use to call the basic search according to how you've configured it in the Account Manager under IDX Search > Search Style.
What's Next?
Next, you add the particular page name that you're trying to access, which would be one of four pages:
index.cfm (starting criteria page) map.cfm (map search page) searchresults.cfm (standard thumbnail view page) searchdetail.cfm (only for individual listing display)
And Then...
After the page name, you add a question mark, followed by the query string/URL parameters, each separated by the ampersand sign (&):
?Parameter1=XXXX&Parameter2=YYYY&Parameter3=ZZZZ
Now, The Good Stuff...
Here are the various parameters you can put into the query string. All parameters are optional.
For parameters with SPACES, such as city names, replace spaces with a plus sign (+). Example: 'East Point' becomes 'East+Point'.
For parameters with APOSTROPHES, such as subdivisions, replace single apostophes with two consecutive apostophes (''). Example: O'Dell's Run becomes O''Dell''s Run. Make sure that you use two apostrophes, NOT the double quote symbol.
| Field Name | Used For | Possible Values | Default | Example |
|---|---|---|---|---|
| KeyField | Determining the primary criteria to search on | City, ListingID, Subdivision, County, PostalCode, SchoolName | City | KeyField=City |
| City | Search by city | 'All' or distinct city names, separated by commas | All |
City=All
City=Atlanta,East+Point |
| State | Search by state, primarily for DynaMap | 'All' or distinct state names, separated by commas | All |
State=All
State=GA State=NC,SC |
| PropertyTypeID | Search by property type |
'All' or numeric values 1-12 separated by commas,
where:
1 - Single Family 2 - Multifamily 3 - Commercial 4 - Land Lots 5 - Acreage and Farms 6 - Condos / Townhomes 7 - Rentals 8 - Co-op 9 - Mobile Homes 10 - Lake and Resort 11 - Commercial Rentals 12 - Business Opportunity |
1 |
PropertyTypeID=All
PropertyTypeID=1,6 |
| County | Search by county | County name | (no default) | County=Fulton |
| PostalCode | Search by ZIP/Postal Code | ZIP Codes, separated by commas | (no default) | PostalCode=30101,30102 |
| Subdivision | Search by subdivision | Full (or partial) subdivision name | (no default) |
Subdivision=Fair
Subdivision=Fairfield |
| SchoolName | Search by school name | Full (or partial) school name | (no default) |
SchoolName=Oak
SchoolName=Oak+Lawn |
| SchoolType | Used with SchoolName | HighSchool, MiddleSchool, ElementarySchool | HighSchool | SchoolType=HighSchool |
| ListingID | MLS Number/Listing ID; Only use with KeyField=ListingID | Single or comma-separated list of Listing IDs | (no default) |
ListingID=1232321
ListingID=1231223,1242323 |
| Keywords | Search for key words in the body of the listing description; Precede with '!' for negation of term | Comma-separated list of terms | (no default) |
Keywords=golf,master+on+main
Keywords=lake,Alatoona Keywords=foreclosure,!HUD |
| KeywordsOperator | Used with Keywords | 'and' uses all keywords; 'or' uses any keywords | and | KeywordsOperator=and |
| MinPrice | Minimum Price | 0-999999999 | 0 |
MinPrice=0
MinPrice=200000 |
| MaxPrice | Maximum Price | 0-999999999 | 999999999 |
MaxPrice=999999999
MaxPrice=450000 |
| PriceRange | Alternative to MinPrice and MaxPrice in a single field; Separator is vertical bar | 0-999999999 | 0|999999999 |
PriceRange=0|999999999
PriceRange=250000|450000 |
| Bedrooms | Minimum number of bedrooms | 0+ | 0 | Bedrooms=3 |
| BathsFull | Minimum number of full baths | 0+ | 0 | BathsFull=2 |
| YearBuilt | Year property built (or earlier/later, depending on YearBuiltOperator) | Four-digit year or 0 | 0 | YearBuilt=1995 |
| YearBuiltOperator | Whether earlier or later than YearBuilt (also includes equal to YearBuilt) | 'earlier' or 'later' | later | YearBuiltOperator=later |
| Stories | Number of stories |
0, 1, or 2
(2 is for 2 or more) |
0 |
Stories=0
Stories=2 |
| SortOrder | Order search is returned | Asc - ascending by price; Desc - descending by price; New - new/modified in last two weeks shown first | Asc | SortOrder=Asc |
| MaxRows | Maximum rows per page returned | 5, 10, 20 | 10 | MaxRows=10 |
| PhotoLinks | How to show listing photos - 'No' shows thumbnail photos on results; 'Detail' shows detail photos only; 'Yes' shows only listings with photos | 'No', 'Detail', or 'Yes' | No |
PhotoLinks=No PhotoLinks=Detail PhotoLinks=Yes |
| Reciprocity | Show agent/office listings or full MLS search | 'Yes' shows all MLS listings; 'No' shows only agent/office listings | Setting in Admin | Reciprocity=Yes |
| Advanced | Advanced search | 'Yes' or 'No' (default KeyField is 'City', but you can combine fields like Subdivision and PostalCode when 'Yes') | No | Advanced=No |
| StatusCodes | Status of listing | Check with us for valid status codes for your MLS | (no default) | StatusCodes=Active |
| ResultsStyle |
Style for results to display; Photo w/ Text (1), DynaMap (2), ListingFlow (5), Photo Gallery (6) |
1, 2, 5, or 6
(Without DynaMap, 1 is only valid value; 5 and 6 only available with 5.0 version) |
1 |
ResultsStyle=1
ResultsStyle=2 |
Special Parameter: LeadSource
There is an additional parameter available for tracking where Leads come from called LeadSource. This can be used to differentiate separate implementations of your central URL. If you've got more than one web site where your URL is plugged in, you can track it! For example:
http://membername.servicename.com/search/index.cfm?LeadSource=MainWebSite http://membername.servicename.com/search/index.cfm?LeadSource=GoogleAd
With this, you'll be able to track the effectiveness of ALL of your IDX implementations!
Special Note: The Evils of 'Copy and Paste' (Updated 2/18/10)
As you use the API, you may also encounter some additional URL parameters - either CFID/CFToken or JSessionID. These are two special variables related to ColdFusion, which is the web application language used to create ListingWare. Previously, you could cause issues with visitor tracking and registration if you included these in your links. This shouldn't be a problem any longer, as we've stopped using them in our links automatically. You may have created links in the past that have them embedded, but it shouldn't be a problem. However, it's good practice to remove them if you encounter them.
API Examples
You can use these parameters to either create custom searches that appear at the click of a button or link, or tailor the starting search page so that certain parameters are pre-selected. These examples work with any of our versions. Try them with your own URL - just substitute yours where it has http://yourname.servicename.com below. But make sure you check out all of the parameters you can use to get the most out of the API!
To provide different starting search parameters, start with the index.cfm page.
http://yourname.servicename.com/search/index.cfm?City=Acworth,Alpharetta&MinPrice=400000&MaxPrice=1000000
http://yourname.servicename.com/search/index.cfm?PropertyTypeID=6&MinPrice=250000&Advanced=Yes
To start with DynaMap search, use the map.cfm page. Second example uses City and State to default to a particular location at the center of the search.
http://yourname.servicename.com/search/map.cfm (Default DynaMap search in metro area)
http://yourname.servicename.com/search/map.cfm?City=Acworth&State=GA&MinPrice=200000&MaxPrice=500000
To create a one-click search, use the searchresults.cfm page.
http://yourname.servicename.com/search/searchresults.cfm?KeyField=Subdivision&Subdivision=Fairfield&SortOrder=Desc
To show only all of your own listings.
http://yourname.servicename.com/search/searchresults.cfm?PropertyTypeID=All&Reciprocity=No
Select several listings to highlight with searchresults.cfm
http://yourname.servicename.com/search/searchresults.cfm?keyfield=listingid&listingid=1231223,1221447,1213435
Show an individual listing with searchdetail.cfm
http://yourname.servicename.com/search/searchdetail.cfm?keyfield=listingid&listingid=1231223