Documentation

The Plat listings API.

Plat serves MLS listing data through one OData 4.01 endpoint, with fields named as the RESO Data Dictionary names them. Every request carries an OAuth2 bearer token, and every response is filtered to the fields your licence tier allows.

Examples use $PLAT_HOST, which is https://plat.blacktreegrouptx.com. All paths below are relative to it.

Sandbox

Sandbox keys return invented listings on the same endpoints and the same schema as production, so an integration can be finished before any market is licensed. Sandbox rows carry OriginatingSystemName SAMPLE, and every sandbox response includes the header X-Plat-Sandbox: true.

Authentication

Exchange your client credentials for a bearer token with the OAuth2 client credentials grant. The endpoint accepts a form-encoded body, a JSON body, or the pair in an HTTP Basic header.

curl -X POST "$PLAT_HOST/v1/token" \
  -d grant_type=client_credentials \
  -d client_id="$PLAT_CLIENT_ID" \
  -d client_secret="$PLAT_CLIENT_SECRET"

{
  "access_token": "plat_at_3f9c...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "IDX"
}

Tokens last 8 hours (expires_in: 28800). They are opaque strings, not JWTs, so revoking a key stops its tokens immediately. scope reports your licence tier. A wrong client id and a wrong secret return the same 401 invalid_client, so the endpoint cannot be used to discover which ids exist.

Requests and responses

Send the token as Authorization: Bearer <token>. Responses are JSON in the OData envelope: rows in value, and @odata.count when you ask for it with $count=true.

curl -G "$PLAT_HOST/v1/listings/data/Property" \
  -H "Authorization: Bearer $PLAT_TOKEN" \
  --data-urlencode "\$filter=StandardStatus eq 'Active' and ListPrice le 750000" \
  --data-urlencode "\$select=ListingKey,UnparsedAddress,ListPrice,BedroomsTotal" \
  --data-urlencode "\$orderby=ListPrice desc" \
  --data-urlencode "\$top=25" \
  --data-urlencode "\$count=true"

{
  "@odata.context": "$metadata#Property",
  "@odata.count": 12,
  "value": [
    {
      "ListingKey": "SAMPLE-0001",
      "UnparsedAddress": "1104 W Lynn St, Austin, TX 78703",
      "ListPrice": 749000,
      "BedroomsTotal": 3
    }
  ]
}

Resources

A resource marked Soon returns 501 not_implemented until it is served.

Query options

$filter

Operators bind in this order, loosest first: or, and, not, then comparisons. Parentheses override it.

Missing values

A comparison against a field the row does not have is false, except eq null (true) and ne null (false). ClosePrice gt 0 never matches an active listing, and neither does ClosePrice le 0.

StandardStatus

Always one of: Active, Active Under Contract, Canceled, Closed, Coming Soon, Delete, Expired, Hold, Incomplete, Pending, Withdrawn. The value the MLS sent is kept in MlsStatus.

Geospatial

geo.distance measures great-circle distance in metres. geo.intersects tests whether a listing falls inside a polygon; additional rings are treated as holes. Coordinates are WKT, longitude before latitude.

# Within 5 km of a point. WKT order is longitude, then latitude.
$filter=geo.distance(Location, geography'POINT(-97.7404 30.2747)') le 5000

# Inside a drawn boundary. The ring must close on its first point.
$filter=geo.intersects(Location, geography'POLYGON((-97.775 30.24, -97.735 30.24, -97.735 30.27, -97.775 30.27, -97.775 30.24))')

Listings without coordinates never match a geospatial predicate. Coordinates of exactly 0, 0 are treated as missing when a feed is ingested.

Text search

search.text(Field, 'terms', minMatches) matches on whole terms, case insensitive, with punctuation ignored. It is not a geocoder.

Pass minMatches to override the default. Values above the number of terms mean every term.

# Partial or misspelled address: 2 of these 3 terms must match
$filter=search.text(RawAddressSearchText, '2214 barton spring')

# Require every term
$filter=search.text(RawAddressSearchText, '2214 barton springs', 1000)

# Remarks keyword search, all terms by default
$filter=search.text(KeywordSearchText, 'pool renovated')

$expand

Licence rules apply to expanded rows exactly as they apply to the listing.

Licence tiers

Your key carries one tier. Fields the tier does not cover are removed before the response is sent, on every row and every expanded row. An unrecognized tier is treated as IDX, the narrowest.

plat_* fields describe provenance: the source feed, when the row was ingested, and the raw values the MLS sent. They are served under BBO only.

Freshness and history

Each licensed feed is replicated every 15 minutes, walking ModificationTimestamp forward from where the last run stopped. A record older than the stored version is ignored, so listings never move backwards in time.

When one of these fields changes, the old and new values are recorded as a change event: StandardStatus, MlsStatus, ListPrice, ClosePrice, CloseDate, PhotosCount, BedroomsTotal, BathroomsTotalInteger, LivingArea.

Status codes are mapped to StandardStatus only when the mapping is unambiguous. A code that means different things in different markets stays unmapped until that market has an explicit rule, because a guess would put wrong listings behind StandardStatus eq 'Active'.

Errors

Every error uses the same envelope.

{
  "error": {
    "code": "invalid_query",
    "message": "Unterminated string literal at 20"
  }
}