MLS AutoComplete Use Cases

Why this matters

Most MLS apps start with a search box. Before MLS AutoComplete, the usual pattern was to call a general address autocomplete on every keypress, then call MLS Detail to see whether a listing existed. That was slow, and it missed listings whose addresses only exist in MLS data.

/v3/MLSAutoComplete suggests addresses, streets and MLS boards straight from MLS data, plus cities, counties, ZIPs and states, in one call. Every address suggestion already carries the listingId, mlsNumber and mlsBoardCode you need for the next call. It's free for any key with an active MLS plan, so you can call it as the user types.

Note: the /v3/MLSAutoComplete will also complete non-MLS addresses so that you don't have to call /v2/AutoComplete and /v3/MLSAutoCompletefor every keypress. We will eventually lock down this part of the functionality to only people that have a public record data plan (Starter, Growth, etc.) in addition to their MLS plan

Common use cases

Listing search box. Suggest real MLS addresses as the user types, then open the listing with MLS Detail.
Location picker. Let users pick a city, ZIP, county or state, then run MLS Search for that area.
Board picker. Let users find an MLS board by name and get its mls_board_code for filtering.
"Near me" suggestions. Rank address suggestions close to the user (or the map center) first.
Lead and CRM forms. Make sure the address a lead types is one that actually exists in MLS before you store it.

Search types

Pick what to suggest with search_types. Send one code or an array. It defaults to A.

Code	Suggests
`A`	Addresses with an MLS listing
`S`	Streets that carry MLS listings
`B`	MLS boards
`C`	Cities
`N`	Counties
`Z`	ZIP codes
`T`	States

Workflow 1: Address to full listing

Step 1. Suggest addresses as the user types:

{ "search": "1600 Pennsylvania", "search_types": "A" }

Each suggestion includes the IDs you need:

{
  "title": "1600 Pennsylvania Ave # 01, Stoughton MA, Stoughton, MA",
  "searchType": "A",
  "listingId": 10643600511,
  "mlsNumber": "50480527",
  "mlsBoardCode": "mamlspin",
  "boardName": "MLSPIN",
  "latitude": 42.128607,
  "longitude": -71.109801
}

Step 2. When the user picks one, fetch the full record with MLS Detail using the listingId:

{ "listing_id": 10643600511 }

You can also use mls_number with mls_board_code from the same suggestion.

Workflow 2: Place to listing search

Step 1. Suggest places. Including the state in the text narrows it down:

{ "search": "Austin, TX", "search_types": ["C", "Z"] }

Step 2. Pass the chosen place into MLS Search as city + state or zip:

{ "city": "Austin", "state": "TX", "status": "Active", "size": 50 }

Workflow 3: Board picker

{ "search": "Bright", "search_types": "B" }

{ "title": "Bright MLS", "searchType": "B", "mlsBoardCode": "mdbmls-r", "boardName": "Bright", "state": "MD" }

Use mlsBoardCode as mls_board_code in MLS Search, MLS Pins or the MLS Board Utility.

Location biasing

Send latitude and longitude (always together) to rank nearby addresses first. precision (1 to 10) controls how tightly results are pulled toward the point.

{ "search": "123 Main", "search_types": "A", "latitude": 30.2672, "longitude": -97.7431, "precision": 4 }

Biasing only affects address (A) results. City, ZIP and other place results aren't location-ranked, so include the state in the search text instead ("Austin, TX").

Tips

Tip	Why
Wait for 2+ characters, and debounce keystrokes (around 200 to 300 ms)	`search` needs at least 2 characters, and debouncing keeps the box responsive
Check `data.length`, not just the HTTP status	No matches returns HTTP `200` with `"statusCode": 404` in the body
Expect up to 10 suggestions	Results are capped at 10 per call
Restrict browser keys to your domains	If you call AutoComplete straight from a web page, your key is visible. Limit it to your site's domains in your account settings
Mix types in one call when it helps	`["A", "C", "Z"]` gives one box for addresses and places