Leads

Map where your leads are looking

GEThttps://api.ruuster.com/v1/leads/map

Where your leads are looking for homes, as map-ready points. Listing views, favorites and tour requests from the last 30 days, grouped by the viewed listings' locations into clusters, ZIP codes, cities or single listings, with the top areas and the map bounds. One call for a heatmap, dot map or market map; no need to page through leads.

Authentication: x-api-key and x-email headers of an owner or admin
Rate limit: 120 requests per minute per key

View as Markdown

Every listing view, favorite and tour request your leads made on your sites, placed at the location of the listing they looked at (any listing, yours or not) and grouped for a map. Use it for "where are my buyers looking?", a heatmap or dot map of demand, or to compare areas. It is one call: there is no need to list leads and read each one's activity.

In Claude (claude.ai and Claude desktop) and other assistants that show MCP Apps, the leads_map tool's answer comes with an interactive map of these points: zoom, click a circle for its counts, and click a row in the top-areas table to fly there. Nothing extra to call.

The response is counts only. It never names a lead, so it doesn't count against your daily lead-row quota. For who is behind the activity, use List active leads; for one listing's viewers, List a listing's viewers.

Query parameters

Name	Type	Default	Description
`from`	date	30 days before `to`	First day, `YYYY-MM-DD` in America/Chicago, included. Activity is kept for 30 days, so no earlier than 30 days ago
`to`	date	tomorrow	Day after the last day, `YYYY-MM-DD`, excluded. The default includes today
`groupBy`	`cluster` \| `zip` \| `city` \| `listing`	`cluster`	How points are grouped: `cluster` is a grid sized to the area your leads cover, best for a heatmap; `zip` and `city` give one point per ZIP code or city; `listing` gives one point per listing with its address
`agentId`	string		Only leads assigned to this agent (an `agentId` from List agents)
`limit`	integer	`300`	Most points returned, 1 to 1000. The most active points are kept
`sources`	`0` \| `1`	`0`	`1` adds, for every point and area, how many listing views happened on Ruuster versus on other sources your CRM recorded (portals, IDX sites). Not with `agentId`

Response

Field	Description
`groupBy`	The grouping used
`cellDegrees`	Grid cell size in degrees when `groupBy` is `cluster` (0.005 to 0.25), otherwise null
`totals.views`, `favorites`, `tourRequests`	All activity in the range, mapped or not
`totals.leads`	Distinct leads behind that activity
`totals.listings`	Distinct listings they looked at
`totals.mappedListings`, `unmappedListings`	Listings placed on the map, and those with no location on record
`bounds`	`south`, `west`, `north`, `east` of every mapped listing; null when nothing was mapped
`focus`	The same four edges around the core of the activity (the middle 95% of mapped listings), so a few far-away views don't zoom the map out. Fit the map to this; clusters are sized from it
`points`	One per group, most distinct leads first: `lat`, `lng` (the activity-weighted center), `views`, `favorites`, `tourRequests`, `leads`, `listings`, `medianPrice` (asking price), `label` ("City, ST ZIP"); with `groupBy=listing` also `propertyId` and `address`
`pointsOmitted`	Points left out by `limit`
`areas`	The top 20 cities by distinct leads, whatever the grouping: `city`, `state`, `lat`, `lng`, `views`, `favorites`, `tourRequests`, `leads`, `listings`, `medianPrice`
`ruusterViews`, `outsideViews`, `ruusterShare`	With `sources=1`, on `totals`, each point and each area: listing views on Ruuster (the same as `views`), listing views your CRM recorded from other sources, and Ruuster's share of the two (0 to 1, null with no views). `totals` also has `ruusterLedPoints` and `ruusterLedAreas`, how many returned points and areas have a share above 0.5

meta.range echoes the days mapped and meta.eventsAvailableFrom the earliest day you can ask for. If a range holds more than 60,000 events, the first 60,000 are mapped and meta.truncated is true; ask for fewer days to see the rest.

Request

curl -s "https://api.ruuster.com/v1/leads/map?groupBy=zip&limit=3" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"

const res = await fetch("https://api.ruuster.com/v1/leads/map?groupBy=zip&limit=3", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);

import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads/map?groupBy=zip&limit=3",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])

{ "ok": true, "data": { "groupBy": "zip", "cellDegrees": null, "totals": { "views": 1085, "favorites": 41, "tourRequests": 9, "leads": 212, "listings": 871, "mappedListings": 866, "unmappedListings": 5 }, "bounds": { "south": 33.4012, "west": -84.9133, "north": 34.6127, "east": -83.8021 }, "focus": { "south": 33.7108, "west": -84.6655, "north": 34.3394, "east": -84.1302 }, "points": [ { "lat": 34.0391, "lng": -84.3422, "views": 64, "favorites": 4, "tourRequests": 1, "leads": 23, "listings": 41, "medianPrice": 845000, "label": "Roswell, GA 30075" }, { "lat": 34.0702, "lng": -84.2711, "views": 51, "favorites": 2, "tourRequests": 0, "leads": 19, "listings": 37, "medianPrice": 699000, "label": "Alpharetta, GA 30009" }, { "lat": 33.9512, "lng": -84.5498, "views": 38, "favorites": 3, "tourRequests": 2, "leads": 17, "listings": 30, "medianPrice": 512500, "label": "Marietta, GA 30064" } ], "pointsOmitted": 118, "areas": [ { "city": "Roswell", "state": "GA", "lat": 34.0288, "lng": -84.3497, "views": 112, "favorites": 6, "tourRequests": 2, "leads": 38, "listings": 77, "medianPrice": 799000 } ] }, "meta": { "range": { "from": "2026-09-19", "to": "2026-10-19", "tz": "America/Chicago" }, "eventsAvailableFrom": "2026-09-18" } }

Ruuster and other sources

With sources=1, listing views your CRM recorded from other sources (Ylopo, Zillow, Realtor.com, RealScout, your IDX site and so on) are placed on the same map. Ruuster's own views are counted from Ruuster's activity, and the copies of them that your CRM holds (source Ruuster, or App before May 2026) are left out so nothing is counted twice. Views with no source recorded are left out. Other-source views are counted only from the day Ruuster began recording your leads' activity for the API, so both sides cover the same days. Other-source views have no listing or lead attached, so they never add to leads or listings. With groupBy=listing, each place other-source views happened is its own point, with no propertyId or address, listed after your listings (up to half of limit of them), so every property shows on the map. They come only from CRMs that send listing events back to Ruuster, so an account whose CRM sends none shows 0 outside views.

Drawing the map

Plot points by lat and lng, sized or colored by leads (how many people) or views (how much attention), and fit the view to focus (or bounds to show every point). areas makes a ready summary table beside the map. Listing locations come from the MLS record; a listing with no location is counted in the totals but not placed.