Model MatchHelp

Sales

Draw a map viewport: listing points or grid clusters

postapi.modelmatch.com/v1/sales/map

One call for a whole map viewport. Send the visible bounds (and optionally zoom) plus the usual sales filters. When the matches fit in limit the response is individual point rows (id, coordinates, price, status, beds/baths/sqft); otherwise it is cluster rows, one per grid cell, each with a count, the centroid of its listings and an approximate median list price. total is the exact number of matching listings in the box. Billing: each element of data is billed like a list row (1 credit), so limit bounds the cost of one call. Use POST /v1/sales/count with flatFilters.geoBounds for a free count.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Body application/json

advancedFiltersone of
Show child attributes
Option 1object
Show child attributes
childrenone of[]required

Array of filter expressions (AND)

Same shape as its parent.

typeenumrequired
Options:and
Option 2object
Show child attributes
childrenone of[]required

Array of filter expressions (OR)

Same shape as its parent.

typeenumrequired
Options:or
Option 3object
Show child attributes
childone ofrequired

Same shape as its parent.

typeenumrequired
Options:not
Option 4object
Show child attributes
fieldstringrequired
openumrequired

Comparison operator. exists means the field has a REAL value: on fields whose source records an unknown as an in-domain value (e.g. beds, squareFeet, lotSquareFeet, where an unrecorded measurement is stored as 0), those docs count as NOT existing. neq keeps docs with no value — it removes only what is known to equal the value, matching the reading of an exclusion.

Options:eqneqgtgteltltebetweeninmatchgeoDistanceexists
typeenumrequired
Options:filter
valuenull

Comparison value

boundsobjectrequired

The cell's extent

Show child attributes
eastnumberrequired
northnumberrequired
southnumberrequired
westnumberrequired
filtersone of
Show child attributes
Option 1object
Show child attributes
childrenone of[]required

Array of filter expressions (AND)

Same shape as its parent.

typeenumrequired
Options:and
Option 2object
Show child attributes
childrenone of[]required

Array of filter expressions (OR)

Same shape as its parent.

typeenumrequired
Options:or
Option 3object
Show child attributes
childone ofrequired

Same shape as its parent.

typeenumrequired
Options:not
Option 4object
Show child attributes
fieldstringrequired
openumrequired

Comparison operator. exists means the field has a REAL value: on fields whose source records an unknown as an in-domain value (e.g. beds, squareFeet, lotSquareFeet, where an unrecorded measurement is stored as 0), those docs count as NOT existing. neq keeps docs with no value — it removes only what is known to equal the value, matching the reading of an exclusion.

Options:eqneqgtgteltltebetweeninmatchgeoDistanceexists
typeenumrequired
Options:filter
valuenull

Comparison value

flatFiltersobject
Show child attributes
bathsone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
bedsone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
catsAllowedboolean

Lease listings. true: a cats-OK token. false: No, or dogs-only.

cityone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
countyone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
dogsAllowedboolean

Lease listings. true: a dogs-OK token. false: No, or cats-only.

elementarySchoolone of | null

Elementary school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "elementarySchool".

Show child attributes
Option 1string
Option 2string[]
fipsone of | null

5-digit county FIPS code — the exact-code escape hatch for county (which also accepts a county name).

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
fireplaceboolean

true: the listing has a fireplace. false: it says it does not. Rows with no answer match neither value.

garageSpacesone of | null

Garage spaces (e.g. {gte: 2}). Rows with no garage count are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
geoBoundsobject | null

Map viewport {north, south, east, west} in degrees: only listings inside the box. west greater than east crosses the antimeridian. Unlike geoPoint (a radius) this is the shape a map reports. Applies to list, count and analytics alike.

Show child attributes
eastnumberrequired
northnumberrequired
southnumberrequired
westnumberrequired
geoPointobject | null

Radius search — { lat, lon, radius } (e.g. radius "15mi" or "24km") — around any office on the agent's record; with locationSource office the CURRENT office, production their transactions.

Show child attributes
latnumberrequired
lonnumberrequired
radiusstringrequired
hasHoaboolean

true: the listing says it has an association, or carries a positive HOA fee. false: positive evidence of none (association flag N, or an explicit $0 fee) and no contradicting signal. A row with neither signal matches neither value.

highSchoolone of | null

High school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "highSchool".

Show child attributes
Option 1string
Option 2string[]
hoaFeeobject | null

Monthly-equivalent HOA fee in dollars: a quarterly fee is divided by 3, an annual fee by 12, and so on, so {lte: 300} means "at most $300 a month" whatever the listing's payment frequency. Only rows with a recognized recurring frequency (monthly, quarterly, semi-annual, annual, semi-monthly, weekly) are comparable; one-time, unknown and missing frequencies are excluded. Rows with no fee are excluded unless includeNulls: true (use that to also keep homes with no HOA fee on record, or hasHoa: false). Reads the primary association only.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep rows where the field is missing (a range drops them by default). Requires a bound.

ltnumber
ltenumber
keywordstring | null

Words that must ALL appear in the listing description (public remarks), in any order, case-insensitive. Plain text: operators and punctuation (* ? " ( ) AND OR - :) are not interpreted. At most 200 characters and 12 words; empty or punctuation-only is a 400. Stemmed (granite matches granites), not fuzzy. Listing text is -supplied; see the display rules that apply to it.

listPriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
listingAgentone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
lotSizeSqftone of | null

Lot size in square feet (1 acre = 43,560). Rows with no lot size are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
middleSchoolone of | null

Middle school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "middleSchool".

Show child attributes
Option 1string
Option 2string[]
mlsStatusone of | null
Show child attributes
Option 1enum
Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTD
Option 2enum[]

Match any status

Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTD
Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
modeenum
Options:andor
newConstructionboolean

true: the listing is flagged new construction, or its condition says new / under construction / to be built / pre-construction. false: flagged not-new and no such condition. A row with neither signal matches neither value.

petsAllowedboolean

Lease listings (combine with propertyType: "Residential Lease"). true: cats OK, dogs OK or a plain Yes. false: No, with nothing permitting. Negotiable and detail-only values (size limit, deposit) with no OK token match neither value.

poolPrivateboolean

true: the listing has a private pool. false: it says it does not. Community pools are not distinguished (feeds record them inconsistently). Rows with no answer match neither value.

priceReducedboolean

true: the current list price is below the ORIGINAL list price. false: at or above it. Rows missing either price match neither value. (Not based on previousListPrice, which is unreliable.)

priceReductionPercentobject | null

How far the current list price is below the ORIGINAL list price, in percent of the original: {gte: 5} = cut by at least 5%. Negative means the price was raised. Rows missing either price are excluded unless includeNulls: true. Pair with priceReduced: true to exclude unchanged listings from a lte range.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep rows where the field is missing (a range drops them by default). Requires a bound.

ltnumber
ltenumber
propertyIdone of | null

Parcel id — every sale record of one property (the mmPropertyId on a loan or property record). Loans' propertyId selects the same parcel.

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
propertyTypeone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
saleDateone of | null
Show child attributes
Option 1string

Exact date, or a whole period: YYYY-MM-DD (that day), YYYY-MM (the whole month — "2025-06" = 2025-06-01 through 2025-06-30) or YYYY (the whole year). YYYYMMDD, MM/DD/YYYY, an ISO-8601 datetime and epoch milliseconds are also accepted. An unparseable value is a 400.

Option 2object

Date range. Excludes null/missing-field docs by default; add includeNulls: true to keep them. Bounds accept YYYY, YYYY-MM, YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, a full ISO datetime or epoch milliseconds; an unparseable bound is a 400. A partial bound denotes the whole period and expands to the edge that preserves the operator: gte/lt take the period START, gt/lte take the period END — so {gte: "2024"} means on/after 2024-01-01 and {lte: "2024"} means through 2024-12-31.

Show child attributes
gtstring
gtestring
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires a bound.

ltstring
ltestring
salePriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
schoolDistrictone of | null

School district name, one or an array (any-of). Matched case-insensitively with the generic words removed, so Austin Independent School District, Austin ISD and AUSTIN select the same listings. Matches the district assigned at any level (elementary, middle or high). It is a name match, not a boundary lookup: Austin would also match a district named Austin Achieve, so pair it with a location filter. List the available values for an area with POST /v1/sales/analytics/chart and slice: "schoolDistrict".

Show child attributes
Option 1string
Option 2string[]
soldAgentone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
soldPriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
sqftone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
stateone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
storiesone of | null

Number of stories: 3, [1, 2] or {lte: 1} for single level. Where the listing has no stories value the building's story count is used instead, which for a condo is the whole building. Rows with neither are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
waterfrontboolean

true: waterfront property. false: it says it is not. Rows with no answer match neither value.

yearBuiltone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
zipone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
zipCodeone of | null

ZIP code. Canonical key on sales (matches loans zipCode and the response DTO); zip is an alias kept for cross-entity parity.

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
limitinteger

Most point rows to return (default 250, max 1000). It is also the auto switch-over: more matches than this come back as clusters. Billing counts each element of data, so this bounds the cost of one call.

modeenum

auto (default): individual point rows when the matches fit in limit, otherwise cluster rows. points: always individual rows, newest first, capped at limit (truncated says when more matched). clusters: always grid cells.

Options:autopointsclusters
periodenum

Date window for loans / sales / market endpoints. Accepts every Period value plus rolling windows: last30Days / last60Days / last90Days (today minus 30 / 60 / 90 days through today), previousMonth (the last complete calendar month) and currentMonth (the 1st of this month through today). All windows are resolved in UTC with inclusive calendar-date bounds. Rolling windows are only accepted by the loans, sales and market endpoints (list, count, breakdowns, analytics summary / time-series / chart); originators / companies / branches / agents / offices endpoints return 400 for them.

Options:2017201820192020202120222023202420252026last3Monthslast6Monthslast12Monthslast14Monthslast16Monthslast18Monthslast24MonthsyearToDateallTimelast30Dayslast60Dayslast90DayspreviousMonthcurrentMonth
zoominteger

Web-map zoom level (0-22). Sets the cluster grid precision (about 8 cells across a 256 px tile). Omitted: derived from the width of bounds.

Responses

200objectPoints or clusters for the viewport
Show attributes
dataone of[]required
Show child attributes
Option 1object
Show child attributes
bathsnumber | nullrequired
bedsnumber | nullrequired
idstringrequired

Sale document ID

kindenumrequired
Options:point
latnumberrequired
lonnumberrequired
mediaobject

The first listing photo found on the open web, how many were found, and where from. Present on a list or map row only while a non-expired found record exists for THIS listing, otherwise the key is absent. Same caveats as SaleMedia: third-party links, attribute to source.host, they can stop resolving.

pricenumber | nullrequired

Sold price for a closed sale (SLD), otherwise the list price, in dollars

sqftnumber | nullrequired
statusenumrequired
Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTD
Option 2object
Show child attributes
boundsobjectrequired

The cell's extent

countintegerrequired
keystringrequired

Grid cell as zoom/x/y (web-mercator tile coordinates)

kindenumrequired
Options:cluster
latnumberrequired

Centroid of the listings in the cell (not the cell centre)

lonnumberrequired
medianListPricenumber | nullrequired

Approximate median list price of the cell's listings, in dollars (list price for every status, sold included)

modeenumrequired

What data holds: all point rows or all cluster rows

Options:pointsclusters
precisioninteger

Grid zoom level used (clusters only)

totalintegerrequired

Listings inside bounds matching the filters (exact), regardless of how many data rows are returned

truncatedbooleanrequired

points: more listings matched than limit, so data is the newest limit. clusters: more cells existed than the cap, so the smallest were left out.

400objectValidation error. Includes unresolvable location filters: a `city`/`county`/`state`/`zip` value that does not match a recognized location returns 400 rather than an empty result set. Resolve the name with `instantSearch` (use an id from its `results.locations[]`) or `suggestLocations` (use the `id` of a `source: "dictionary"` result), then pass that id back as the filter value.
401objectUnauthorized
403objectForbidden (authenticated, but missing required context — e.g. no active organization)
404objectNot found
413objectResponse payload too large — detail endpoint capped to fit Lambda response limits
503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.