MLS Pins Use Cases

Why this matters

Maps need a lot of points, fast, without the weight of full listing records. /v3/MLSPropertyMapping returns one small point per listing, with just enough to draw, label and color a marker:

{
  "listingId": 10643344265,
  "publicId": 167082965,
  "latitude": 30.27157211303711,
  "longitude": -97.727783203125,
  "listingPrice": 595000,
  "status": "Active",
  "listingPropertyType": "Residential",
  "listingDate": "2026-06-23"
}

It takes the full MLS Search request: every filter, plus count, size and resultIndex. It returns up to 10,000 pins per page (MLS Search returns up to 250 records).

Common use cases

Map view in a home-search app. Show every listing that matches the user's filters inside the visible map area.
Pins first, details on click. Keep the map light, and call MLS Detail only for the pin the user opens.
Neighborhood or territory maps. Draw a polygon (or several) and show what's listed inside.
Prospecting maps. Plot expired or withdrawn listings in a ZIP for agent outreach.
Decide whether to cluster. Check the count first, then draw individual pins or clusters.

Workflow 1: Map viewport

Step 1. Turn the visible map area into a polygon (closing the shape with the first point) and check how many pins it holds:

{
  "polygon": [
    { "lat": 30.30, "lon": -97.78 },
    { "lat": 30.30, "lon": -97.70 },
    { "lat": 30.24, "lon": -97.70 },
    { "lat": 30.24, "lon": -97.78 },
    { "lat": 30.30, "lon": -97.78 }
  ],
  "status": "Active",
  "count": true
}

Step 2. If the count is manageable, drop count and request the pins with a size large enough to cover it (up to 10,000). If it's very large, cluster on your side, or ask the user to zoom in.

Step 3. When the user clicks a pin, fetch the listing with MLS Detail using the pin's listingId:

{ "listing_id": 10643344265 }

Use multi_polygon instead of polygon to cover several areas at once, such as a set of neighborhoods.

Workflow 2: Prospecting map

Plot off-market listings that changed recently, for agent outreach:

{
  "zip": "78704",
  "status": ["Expired", "Withdrawn", "Canceled"],
  "modification_timestamp_min": "2026-09-01",
  "size": 2000
}

Some boards record expired and canceled listings as Withdrawn, so include all three. See Find Listings at Different Lifecycle Stages/Statuses.

One pin per property

Pins default to one pin per property (latest_only: true), so a home that was listed three times shows up once, at its latest listing. That way the map count matches the number of properties.

This is the one difference from MLS Search, which returns every listing by default. To compare totals between the two, send latest_only: true to MLS Search, or latest_only: false here to get a pin for every listing. Multi-family properties can still show one pin per unit.

Tips

Tip	Why
Run `count: true` before drawing big areas	It tells you whether to draw pins or clusters
Expect some pins without coordinates	A few listings have no latitude/longitude. Skip them when drawing
Don't send `fields`, `field_sections`, `sort` or `public`	They're accepted but have no effect. Pins always return the fixed point shape
Page with `resultIndex` for very large areas	Result sets over 100,000 listings can't be paged. Narrow the area or add filters
Filter the same way you search	Pins and MLS Search take the same filters, so the map and the list view always match