Sorting & Excluding Results

sort

Every physically-sortable field in the v3 MLS record is sortable by its dot-path — there's no hardcoded allowlist to consult. Numeric, date, and boolean fields sort directly; string fields sort on their .keyword subfield automatically (you don't need to add .keyword yourself). Arrays and nested-record fields (e.g. listingPriceChangeList, openHouses) aren't sortable — there's no single scalar to order by.

{
  "city": "Austin",
  "state": "TX",
  "sort": { "listingPrice": "desc" }
}

Multiple fields sort in the order given:

{ "sort": { "listingDetails.beds": "desc", "listingPrice": "asc" } }

Friendly aliases

A set of v2-style friendly names resolve to their v3 path automatically, so existing v2 sort payloads keep working:

Defaults & tie-breaking

• If you don't pass sort, results default to modificationTimestamp desc.
• Radius searches (latitude/longitude/radius with no explicit sort) automatically sort by distance, nearest first.
• A listingId asc tie-breaker is always appended to whatever sort you request, so pagination is stable and deterministic — two listings with identical sort values won't randomly swap order across pages.

Errors

A field that isn't sortable (a typo, or an array/nested field) returns 400 INVALID_SORT_FIELD with a suggestion:

{ "sort": { "listing_price": "asc" } }

→ if the exact key isn't recognized, the error suggests the nearest valid sortable field or alias.

exclude

exclude takes an array of filter objects — anything you can filter for elsewhere in the request (any grouped field: status, price ranges, feature values, agent fields, etc.) can be filtered out the same way.

{
  "state": "TX",
  "exclude": [
    { "status": "Closed" }
  ]
}

→ every result must NOT have status: "Closed".

The important rule: fields inside ONE exclude item are ANDed before negating

This trips people up, so it's worth being explicit. Each object in the exclude array is negated as a whole — if an item has multiple fields, a listing is only excluded when it matches all of them together.

Two separate exclude items → two independent exclusions (broader):

{
  "exclude": [
    { "status": "Closed" },
    { "city": "Austin" }
  ]
}

This excludes anything Closed, and separately excludes anything in Austin. An active Austin listing is excluded (matches the 2nd item); a closed Dallas listing is excluded (matches the 1st item).

One exclude item with multiple fields → a single combined exclusion (narrower):

{
  "exclude": [
    { "status": "Closed", "city": "Austin" }
  ]
}

This excludes ONLY listings that are both Closed AND in Austin. A closed listing in Dallas is kept (it doesn't match city: Austin). An active listing in Austin is kept (it doesn't match status: Closed).

Choose one big object when you want to exclude a specific combination; choose separate array entries when you want to exclude several independent conditions.

Composing with and / or

exclude can be nested inside and/or compound items too, since compound items accept the same filter groups plus exclude:

{
  "or": [
    { "status": "Active" },
    { "status": "Pending", "exclude": [{ "has_open_houses": true }] }
  ]
}

Legacy shape stays valid

The v2-style single-field exclude shape (exclude: [{ "listing_property_type": "Land" }]) still works unchanged — listing_property_type (and every other filter field) is just one of the generalized exclude group's members.