Roomvu MLS Hub — Web API guide
The hub collects real-estate listings, agents, offices, open houses and
photos from many MLS feeds and serves them as one read-only RESO Web
API. It speaks OData v4 and the RESO Data Dictionary 2.0. If you have
used another RESO Web API (Bridge, Trestle, CREA DDF, MLS Grid), this one
works the same way: a token, $metadata, entity sets, $filter and next
links.
| What | Where |
|---|---|
| Service root | https://mlshub.roomvu.com/api/odata/ |
| Metadata (the contract) | https://mlshub.roomvu.com/api/odata/$metadata |
| Token | POST https://mlshub.roomvu.com/api/oauth/token |
| Entity sets | Property, Member, Office, OpenHouse, Media, Lookup, and the hub's HubFeed (your feeds) |
| Format | JSON, OData-Version: 4.0 |
| Field reference | https://mlshub.roomvu.com/api/docs/reference (generated from $metadata) |
| OpenAPI 3 | https://mlshub.roomvu.com/api/docs/openapi.json, browsable in Swagger UI |
| Client portal | your feeds, usage, a data browser (your data through the API, with the request behind each page), your security log, allowed IPs and secret rotation — see the portal guide |
$metadata is the authoritative contract. This guide, the field
reference and the OpenAPI file explain it; when they disagree,
$metadata wins (and please tell us).
Contents
- 1. Getting started
- 2. Concepts
- 3. Authentication
- 4. Replication guide
- 4a. Reading the data: filters and the seek pointer
- 5. Query reference
- 6. Resources and fields
- 7. Media
- 8. Errors and rate limits
- 9. Extensions
- 10. Compatibility and versioning
- 11. FAQ
- 12. Changelog
1. Getting started#
You need three things from the hub's administrator: the service root, a
client_id and a client_secret. Then, in about five minutes:
Step 1 — get a token. Send your id and secret with HTTP Basic authentication:
curl -sS -u "$HUB_CLIENT_ID:$HUB_CLIENT_SECRET" \
-d grant_type=client_credentials \
https://mlshub.roomvu.com/api/oauth/token
{ "access_token": "3q9Vx…", "token_type": "Bearer", "expires_in": 3600 }
Step 2 — see what you may read. Send the token on every request:
curl -sS -H "Authorization: Bearer $TOKEN" https://mlshub.roomvu.com/api/odata/
{ "@odata.context": "https://mlshub.roomvu.com/api/odata/$metadata",
"value": [ { "name": "Property", "kind": "EntitySet", "url": "Property" },
{ "name": "Member", "kind": "EntitySet", "url": "Member" },
"…" ] }
Step 3 — read the first records. Five listings, oldest change first, a few fields:
curl -sS -G -H "Authorization: Bearer $TOKEN" https://mlshub.roomvu.com/api/odata/Property \
--data-urlencode '$orderby=HubModificationTimestamp' \
--data-urlencode '$top=5' \
--data-urlencode '$select=ListingKey,StandardStatus,ListPrice,City,HubModificationTimestamp'
{
"@odata.context": "https://mlshub.roomvu.com/api/odata/$metadata#Property",
"@Hub.ReplicationBound": "2026-10-10T08:00:00.123456Z",
"value": [
{ "ListingKey": "X1000001", "StandardStatus": "Active", "ListPrice": 649900,
"City": "Sampletown", "HubModificationTimestamp": "2026-10-01T12:00:00.000001Z" },
"…"
],
"@odata.nextLink": "https://mlshub.roomvu.com/api/odata/Property?$skiptoken=eyJ…"
}
The whole script, ready to run:
#!/bin/sh
# From credentials to the first records with curl (and jq to read the JSON).
#
# HUB_ROOT=https://hub.example.com HUB_CLIENT_ID=hub_... HUB_CLIENT_SECRET=... sh first-records.sh
set -eu
# 1. Exchange the client id and secret for a bearer token (valid one hour).
TOKEN=$(curl -sS -u "$HUB_CLIENT_ID:$HUB_CLIENT_SECRET" \
-d grant_type=client_credentials \
"$HUB_ROOT/api/oauth/token" | jq -r .access_token)
# 2. See what you may read: the entity sets of your client.
curl -sS -H "Authorization: Bearer $TOKEN" "$HUB_ROOT/api/odata/" | jq '.value[].name'
# 3. The first five listings, oldest change first, a few fields only.
curl -sS -G -H "Authorization: Bearer $TOKEN" "$HUB_ROOT/api/odata/Property" \
--data-urlencode '$orderby=HubModificationTimestamp' \
--data-urlencode '$top=5' \
--data-urlencode '$select=ListingKey,StandardStatus,ListPrice,City,HubFeedKey,HubModificationTimestamp' \
| jq '{bound: ."@Hub.ReplicationBound", next: ."@odata.nextLink", listings: .value}'
# 4. Your feeds: every record names its feed by HubFeedKey.
curl -sS -H "Authorization: Bearer $TOKEN" "$HUB_ROOT/api/odata/HubFeed" | jq '.value[] | {FeedKey, FeedName}'
# 5. A seek read (guide §4a): every Active listing, in the key order, stable while
# the data changes — follow ."@odata.nextLink" as given for the next pages.
curl -sS -G -H "Authorization: Bearer $TOKEN" "$HUB_ROOT/api/odata/Property" \
--data-urlencode 'seek=true' \
--data-urlencode "\$filter=StandardStatus eq 'Active'" \
--data-urlencode '$top=5' \
--data-urlencode '$select=ListingKey,StandardStatus,HubFeedKey' \
| jq '{bound: ."@Hub.ReplicationBound", next: ."@odata.nextLink", listings: .value}'
Next: to keep a copy of the data up to date, read Concepts and the replication guide, or start from a complete client in §4.9.
2. Concepts#
2.1 Feeds#
A feed is one record set with its own key space: one dataset of one
provider (one MLS's data as that platform serves it). Examples:
proptx-trreb (the Toronto board through PropTx), crea-ddf (Canada's
national pool), spark-sbmls (Santa Barbara through Spark). Where a
provider's credentials each see a different part of one dataset, each is
its own feed, with a third part in its code naming the brokerage
(bridge-armls2-rog, bridge-armls2-wusa, …).
Each record belongs to exactly one feed, and says which: HubFeedKey
on every listing, agent, office and open house — a short, stable code of
the form provider-dataset (lowercase a–z, 0–9 and hyphens, at most
32 characters; the provider part is the platform's name). A code never
changes and is never reused. The HubFeed entity set lists your feeds
once — code, name, provider, and the MLS when the whole feed is one MLS.
Read it once per run and join by key; nothing about the feed is repeated
on the records (photos carry nothing about it at all: they belong to
their listing).
A record's key is unique within its feed: (HubFeedKey, key) is
unique across feeds. The same house can come through two feeds (Toronto
listings arrive from TRREB and from CREA's national pool), and the
same agents, offices and open houses can come through several feeds of
one dataset with the same keys. The hub serves every copy, each with
its own feed and key. It never merges them.
2.2 Grants and their modes#
Your client reads the feeds it is granted. By default a new client is granted every feed, every resource and every RESO field. The hub-specific extensions (§2.5) are separate, opt-in per client. The administrator can narrow the defaults when needed.
Each grant has an activation time and a mode:
| Mode | What you receive of that feed |
|---|---|
| Full feed on activation (the default) | Your next poll whose cursor is before the activation time returns every row of the feed, together with your other feeds' normal changes. After that, changes only. |
| Updates only | Only rows that change after the activation time. You never receive the feed's older rows. |
Example: your cursor is 12:00 and you poll every two hours. Feed "Winnipeg" is granted to you at 13:00 in full mode. Your 14:00 poll ("changes since 12:00") returns all of Winnipeg plus the other feeds' changes since 12:00. Your 16:00 poll returns changes only.
2.3 The replication cursor#
Every record has HubModificationTimestamp: the moment the hub's
copy of it last changed (UTC, microseconds). It moves when a stored
value changes, and also when the record's photos or rooms change.
You replicate by asking "everything with HubModificationTimestamp
after my cursor". Each answer tells you your next cursor in the
@Hub.ReplicationBound annotation.
The MLS's own ModificationTimestamp is served too, untouched — but it
is not the cursor. Two feeds' clocks are not comparable, and a photo
change does not move it.
2.4 Removed listings#
The hub never deletes a record it served, and never invents a status. When a listing leaves its feed, you receive the listing itself again (through the cursor), with its values untouched and one of two markers:
| Field | Meaning |
|---|---|
HubNotSeenInFeedSince (Property) |
The feed stopped returning this listing (sold, withdrawn, expired — the feed did not say which). Cleared if it comes back. |
HubProviderDeletedAt (Property, Member, Office, OpenHouse) |
The MLS itself marked the record deleted. |
StandardStatus stays what the MLS last sent. You decide what a removed
listing means for you (hide it, mark it off-market…).
2.5 Extensions#
Everything that is not RESO Data Dictionary is an extension, opt-in
per client: the old platform's source name and prefix of each feed
(source), the origin MLS of each record (origin_mls), synthetic agents
and offices, and the feed's raw extra fields. Without an extension, its
fields are in neither your $metadata nor your data. Extension fields
start with Hub. See §9.
Part of every client, because replication needs them: HubFeedKey,
HubModificationTimestamp, HubNotSeenInFeedSince,
HubProviderDeletedAt, on Property HubMediaModificationTimestamp
(§7.4) (and on OpenHouse the local-time pair of
§6.4), and the HubFeed entity set.
How the hub produced a value (which fields it filled, and from where) and which listings it believes are the same are not part of the API: they are the hub's own diagnostics, kept for its operators.
2.6 What the hub never does#
- No guessing. A value is served only if the MLS sent it, or if it
follows exactly from what the MLS sent (for example
"Street"written as the postal standard's"ST", or a phone number written as+14165550142). Nothing is filled from "what is usually true". A field the MLS left empty isnull. - No merging. Two feeds' copies of one listing stay two records, each with its own feed and key.
- No invented status. A listing that disappears keeps its last status and gets a marker (§2.4).
- No re-interpretation on the way out. You get what is stored, in RESO form. Only the form is adjusted: numbers without trailing zeros, timestamps in ISO 8601, signed links for photos the hub serves itself.
2.7 Data for professionals, and public display#
Some of what a feed carries is meant for real-estate professionals, not
for the public: offer instructions or commission remarks among a
listing's extra fields (HubExtraFields), private remarks, showing
instructions, and agent and office contact details. The hub serves what
your grants allow; it does not decide what may be shown to whom. If you
show data publicly, apply your MLS's display rules (IDX) yourself —
which fields, which listings (for example InternetEntireListingDisplayYN,
InternetAddressDisplayYN) and the attribution each MLS requires.
3. Authentication#
3.1 Getting a token#
The hub uses the OAuth2 client credentials grant (RFC 6749 §4.4).
Send your client_id and client_secret with HTTP Basic authentication
(or as the form fields client_id / client_secret):
POST /api/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
{ "access_token": "3q9Vx…", "token_type": "Bearer", "expires_in": 3600 }
Then send Authorization: Bearer <access_token> on every request.
Never put the id or secret in the URL. Credentials in the query
string are refused with invalid_request, because URLs end up in logs.
3.2 Expiry#
A token lives one hour (expires_in, in seconds). Reuse it until shortly
before it expires, then ask for a new one. If a request answers 401,
get a new token and repeat the request once; a second 401 means your
client was revoked or its secret rotated (see below). A new token does not
cancel older ones: each simply expires. One token per run (or per hour)
is all a replication client needs; the token endpoint allows 10 requests
a minute per address.
3.3 Errors from the token endpoint#
| Status | error |
Meaning |
|---|---|---|
| 400 | invalid_request |
Missing or malformed parameters, or credentials in the URL. |
| 400 | unsupported_grant_type |
grant_type is not client_credentials. |
| 401 | invalid_client |
Unknown client, wrong secret, or the client is revoked. |
| 403 | access_denied |
The credentials are right but your address is not in the client's allowed IP list (§3.7). The description names the address the hub saw. |
| 429 | — | More than 10 token requests a minute from your address. Wait Retry-After seconds. |
3.4 Secret rotation#
An Owner of your team (in the client portal) or the administrator can issue a new secret ("rotate"). Normally the old secret keeps working for 24 hours, so you can switch without an outage: store the new secret, and your next token request uses it.
If the old secret may be compromised, it is stopped at once and every
token issued with it is revoked (the portal's "Secret may be compromised";
see what to do if a secret leaks). Your next request answers
401, and token requests with the old secret answer invalid_client
until you use the new one.
3.5 Revocation#
A revoked client is refused at once: every token answers 401 and no new
token is issued. Ask the administrator to restore it.
3.6 Keeping the secret safe#
Keep it in your secret store, never in source code, URLs or logs. Use HTTPS only. If it leaks, rotate it as "may be compromised" in the client portal at once.
3.7 Allowed IP addresses#
Your client may restrict where it is used from: a list of addresses and CIDR ranges, set by an Owner of your team in the client portal (empty by default: no restriction). When the list is not empty:
- the token endpoint refuses another address with
403{"error": "access_denied"}— only after the secret was verified; - every OData request from another address is refused with
403and the codeIpNotAllowed, even with a valid token issued from an allowed address — a stolen token is useless elsewhere; - photo links (
MediaURL) are not restricted (§7).
The address is the one the hub sees for your request (behind our load balancer, your own public address). If your servers' outbound address changes (a new NAT gateway, a cloud region), update the list first.
4. Replication guide#
Replication keeps a complete, up-to-date copy of the records you are
granted. The pattern is the same for Property, Member, Office and
OpenHouse; each has its own cursor.
4.1 Initial load#
Ask for everything, ordered by the cursor field:
GET /api/odata/Property?$orderby=HubModificationTimestamp&$top=100
Follow @odata.nextLink until a page has none. Do not change the next
link: it carries an opaque $skiptoken and must be used as given. Every
page of one run sees the same upper bound, announced on each page as
@Hub.ReplicationBound.
$top is optional (default 100 for Property, 500 for the others; maximum
200 for Property, 1,000 for the others). Property pages include the
listings' photos and are large (about 6.2 MB per 100 listings), so 100 is
a good size. Make them smaller:
- Send
Accept-Encoding: gzip: the pages travel compressed (about 0.9 MB per 100 listings). - Send
Prefer: omit-values=nullsif your code reads a missing field asnull: most fields of most records are empty, and they are then left out — about 3.3 MB per 100 listings, 0.54 MB compressed. The response confirms it withPreference-Applied: omit-values=nulls. A next link does not carry headers: send the header on every page. Without it, every declared field is present,nullwhen empty (as other RESO Web APIs send them).
(Measured on the hub's development data, 2026-10-11.)
For a complete copy, also ask for the records' photos where they are not included by default (see §4.5); a listing's photos and rooms always come with it:
GET /api/odata/Property?$orderby=HubModificationTimestamp&$top=100
GET /api/odata/Member?$orderby=HubModificationTimestamp&$expand=Media&$top=500
GET /api/odata/Office?$orderby=HubModificationTimestamp&$expand=Media&$top=500
GET /api/odata/OpenHouse?$orderby=HubModificationTimestamp&$top=500
4.2 Store the bound as your cursor#
When the last page arrives (no next link), store its
@Hub.ReplicationBound as your cursor for that resource:
{ "@Hub.ReplicationBound": "2026-10-10T08:00:00.123456Z", "value": [ "…" ] }
The bound is a UTC timestamp with microseconds and a Z. Store it as
text and send it back exactly as received (gt 2026-10-10T08:00:00.123456Z).
The bound is a promise about changes: no change at or below it will appear later. Records still being written while you read are left out of this run and delivered in the next one. So you never miss a record, even one that was being written during your run. (A feed granted or resent to you is the one exception: it is delivered whole, whatever its timestamps — §4.6. Never use the bound or a timestamp to skip a record you receive; always upsert it.)
Every run returns a bound, even when it returns no rows: store it, so your cursor moves forward through quiet periods.
Store the cursor only after the run completes. If a run is interrupted, start it again with the old cursor; you will receive some records twice, which upserting handles.
4.3 Poll for changes#
On every later run, ask for what changed after your cursor:
GET /api/odata/Property?$filter=HubModificationTimestamp gt 2026-10-10T08:00:00.123456Z&$orderby=HubModificationTimestamp&$top=100
(URL-encode the query string in real requests.) Follow the next links, then store the new bound. Repeat at your own interval — every 15 minutes is reasonable.
A request with a gt (or ge) condition on HubModificationTimestamp,
or ordered by it, is a replication request: the hub orders by the
cursor then the key, pages by key (never by offset), applies your grants'
modes, and refuses $skip.
4.4 Upsert by key#
Write every received record as "insert, or replace the one with the same key":
| Resource | Key |
|---|---|
| Property | ListingKey |
| Member | MemberKey |
| Office | OfficeKey |
| OpenHouse | OpenHouseKey |
| Media | MediaKey |
Receiving a record you already have is normal (a record changed during your run comes again in the next run; a feed can be resent).
A key is unique within one feed. Two feeds can carry the same key
value: several feeds of one dataset share their agents, offices and open
houses with the same keys, and an agent the hub synthesized on one feed
can carry another feed's agent id (only with the synthetic extension).
Store each record under (HubFeedKey, key) and you are safe whatever
your feeds.
Photos and rooms are not upserted one by one: each time their record arrives, replace its whole photo list and room list with the ones received (§4.5). Rooms have no key of their own: they are a list inside the listing, not records.
4.5 Photos, rooms and open houses#
- Photos come inside their record. A Property includes its
Mediaarray by default; a Member (agent photo) or an Office (logo, photos) includes it only with$expand=Media. A changed, added or removed photo moves its record'sHubModificationTimestamp— a listing's, an agent's or an office's — so the record comes again with its complete photo list. Replace your stored photo list with the one received.Mediahas no cursor of its own; you never need to read theMediaentity set to replicate. A listing also says when its photo list last changed, inHubMediaModificationTimestamp: a listing that comes again with the same value has the same photos (§7.4). - Rooms always come inside their listing, in its
Roomsproperty — a list ofPropertyRoomsvalues (a complex type: no key;RoomKeyis an ordinary field, empty when the feed sends none). A changed room moves the listing's timestamp the same way; replace your stored room list with the one received.Roomsis a property, not a navigation:$expand=Roomsis refused; a$selectthat leavesRoomsout leaves the rooms out. - Open houses are their own resource with their own cursor. Each
names its listing in
ListingKey. - Agents and offices (
Member,Office) are their own resources with their own cursors. A listing names them by key (ListAgentKey,ListOfficeKey, …). Replicate them as their own resources — each record arrives once — and join by (HubFeedKey, key).$expand=ListAgentis a convenience for looking at a few listings, not a replication tool: an agent with 300 listings would travel 300 times, and an expanded agent never carries its own office or photo ($expandis one level).
4.6 A feed granted later, and a resend#
When a feed is granted to you in full mode, your next poll returns every record of that feed, mixed with the other feeds' changes, whatever their timestamps. Nothing special is needed on your side: upsert as usual.
The administrator can also resend a feed (for example after you lost data). Its activation time becomes "now" and your next poll returns the whole feed again. Again, upsert as usual.
If none of your feeds changed for a while and you store the bound (not the largest timestamp you received), a full feed is delivered exactly once.
A grant or a resend that happens while one of your runs is in progress is picked up, at the latest, by your next run. Nothing is lost either way.
4.7 Removed records#
Check the markers on every received record:
HubNotSeenInFeedSinceset: the listing left its feed.HubProviderDeletedAtset: the MLS deleted the record.
Both arrive through the cursor like any change. To list removed listings
at any time: $filter=HubNotSeenInFeedSince ne null.
4.8 References between records#
A listing names its agents and offices by key (ListAgentKey,
ListOfficeKey, …), an open house its listing (ListingKey). Treat these
as optional links: a key may name a record you are not served.
- The feed never sent that agent or office (some feeds send listings but no agent records; agents of other boards).
- It is an agent or office the hub synthesized from the listing's own
fields: served only with the
syntheticextension. - It belongs to a feed you are not granted, or the listing was not stored (an open house of a listing the feed doesn't serve).
Such a key answers 404 by key, and its $expand navigation is null.
The listing itself always carries the agent's and office's name and phone
in its own ListAgent… / ListOffice… fields.
The other way round — an agent's or an office's listings, an office's
agents — filter on the reference key, within the record's feed (a key is
unique only within one feed): Property?$filter=HubFeedKey eq 'spark-sbmls' and ListAgentKey eq 'M100', Member?$filter=HubFeedKey eq 'spark-sbmls' and OfficeKey eq 'O200' (§5.4). A filter on a reference key matches the
key the listing carries, whether or not you are served the record it
names.
4.9 Complete clients#
Each client below gets a token, reads the service document, replicates
Property (with its photos and rooms), Member and Office (with Media) and
OpenHouse, one cursor each, follows next links, renews the token once
on a 401, waits on 429 and 503, backs off on 504 and network
errors, stores the bound after each completed run, and calls upsert()
for every record — replace that function with your database write. They
use only each language's standard library.
Python#
#!/usr/bin/env python3
"""A complete Roomvu MLS Hub replication client, standard library only (Python 3.9+).
Run it on a schedule (for example every 15 minutes). The first run loads
everything; every later run fetches only what changed since the last run.
HUB_ROOT=https://hub.example.com HUB_CLIENT_ID=hub_... HUB_CLIENT_SECRET=... python3 replicate.py
"""
import base64
import gzip
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
ROOT = os.environ["HUB_ROOT"].rstrip("/")
CLIENT_ID = os.environ["HUB_CLIENT_ID"]
CLIENT_SECRET = os.environ["HUB_CLIENT_SECRET"]
STATE_FILE = os.environ.get("HUB_STATE_FILE", "hub-cursors.json")
# The resources to replicate, the key of each, and what to expand. Photos
# (Media) and rooms come inside their record; Property includes Media by
# default, Member and Office only when asked. Lookup is reference data
# (read it separately).
KEYS = {"Property": "ListingKey", "Member": "MemberKey", "Office": "OfficeKey", "OpenHouse": "OpenHouseKey"}
EXPAND = {"Property": "Media", "Member": "Media", "Office": "Media"}
# Compressed pages, and no null fields: a field missing from a record is null.
# (Drop the Prefer header to receive every declared field, nulls included.)
HEADERS = {"Accept": "application/json", "Accept-Encoding": "gzip", "Prefer": "omit-values=nulls"}
_token = {"value": None, "expires_at": 0.0}
def token():
"""A bearer token, reused until one minute before it expires."""
if _token["value"] and time.time() < _token["expires_at"] - 60:
return _token["value"]
basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
request = urllib.request.Request(
f"{ROOT}/api/oauth/token",
data=b"grant_type=client_credentials",
headers={"Authorization": f"Basic {basic}", "Content-Type": "application/x-www-form-urlencoded"},
method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response:
body = json.load(response)
_token["value"] = body["access_token"]
_token["expires_at"] = time.time() + body["expires_in"]
return _token["value"]
def get(url):
"""GET one page. A 401 gets a new token and one more try; 429/503 wait Retry-After; 504 and network errors back off."""
renewed = False
for attempt in range(6):
request = urllib.request.Request(url, headers={"Authorization": f"Bearer {token()}", **HEADERS})
try:
with urllib.request.urlopen(request, timeout=60) as response:
body = response.read()
if response.headers.get("Content-Encoding") == "gzip":
body = gzip.decompress(body)
return json.loads(body)
except urllib.error.HTTPError as error:
if error.code == 401 and not renewed:
_token["value"] = None # expired or rotated: get a new token, try once more
renewed = True
continue
if error.code in (429, 503):
time.sleep(int(error.headers.get("Retry-After", "30")))
continue
if error.code == 504:
time.sleep(10 * (attempt + 1))
continue
raise RuntimeError(f"{error.code} {error.read().decode()}") from error # 400/403/404, a second 401: fix the request
except urllib.error.URLError:
time.sleep(10 * (attempt + 1))
raise RuntimeError(f"giving up on {url}")
def upsert(resource, record, feeds):
"""Replace with your database write: insert, or update the row with the same feed and key
(HubFeedKey + key: a key is unique within one feed); replace the record's stored photo and
room lists with record["Media"] / record["Rooms"]. feeds[HubFeedKey] is the record's feed."""
feed = feeds[record["HubFeedKey"]]["FeedName"]
removed = record.get("HubNotSeenInFeedSince") or record.get("HubProviderDeletedAt")
print(f"{resource} {feed} {record[KEYS[resource]]}{' (removed)' if removed else ''}")
def read(resource, query, on_record):
"""A seek read (guide §4a): the narrowing $filter, seek=true, then the next links as given.
Returns the read's upper bound (@Hub.ReplicationBound): everything matching up to it was read."""
query = {"seek": "true", "$top": "100", **query}
url = f"{ROOT}/api/odata/{resource}?{urllib.parse.urlencode(query, quote_via=urllib.parse.quote)}"
bound = None
while url:
page = get(url) # an expired next link (400 ExpiredSkipToken) raises: start the read again
for record in page["value"]:
on_record(record)
bound = page.get("@Hub.ReplicationBound", bound)
url = page.get("@odata.nextLink") # follow it exactly as given
return bound
def replicate(resource, cursor, feeds):
"""One run for one resource (guide §4a, use case 1): everything on the first run, then the
window after the cursor. Returns the new cursor (the run's @Hub.ReplicationBound)."""
query = {"$expand": EXPAND[resource]} if resource in EXPAND else {}
if cursor:
query["$filter"] = f"HubModificationTimestamp gt {cursor}"
return read(resource, query, lambda record: upsert(resource, record, feeds)) or cursor
def active_listings(feed_key, feeds):
"""Use case 2: every Active listing of one feed, read consistently while it changes."""
return read("Property", {"$filter": f"HubFeedKey eq '{feed_key}' and StandardStatus eq 'Active'"}, lambda record: upsert("Property", record, feeds))
def main():
state = json.load(open(STATE_FILE)) if os.path.exists(STATE_FILE) else {}
granted = {entity["name"] for entity in get(f"{ROOT}/api/odata/")["value"]}
# Your feeds, once per run: every record names its feed by HubFeedKey.
feeds = {feed["FeedKey"]: feed for feed in get(f"{ROOT}/api/odata/HubFeed")["value"]}
for resource in KEYS:
if resource not in granted:
continue
state[resource] = replicate(resource, state.get(resource), feeds)
# Save after each completed run only: an interrupted run is simply repeated.
with open(STATE_FILE, "w") as file:
json.dump(state, file, indent=2)
if __name__ == "__main__":
main()
PHP#
<?php
// A complete Roomvu MLS Hub replication client in plain PHP 8.1+ (ext-curl and ext-json only).
//
// Run it on a schedule (for example every 15 minutes). The first run loads
// everything; every later run fetches only what changed since the last run.
//
// HUB_ROOT=https://hub.example.com HUB_CLIENT_ID=hub_... HUB_CLIENT_SECRET=... php replicate.php
declare(strict_types=1);
$root = rtrim((string) getenv('HUB_ROOT'), '/');
$clientId = (string) getenv('HUB_CLIENT_ID');
$clientSecret = (string) getenv('HUB_CLIENT_SECRET');
$stateFile = getenv('HUB_STATE_FILE') ?: 'hub-cursors.json';
// The resources to replicate, the key of each, and what to expand. Photos
// (Media) and rooms come inside their record; Property includes Media by
// default, Member and Office only when asked. Lookup is reference data
// (read it separately).
const KEYS = ['Property' => 'ListingKey', 'Member' => 'MemberKey', 'Office' => 'OfficeKey', 'OpenHouse' => 'OpenHouseKey'];
const EXPAND = ['Property' => 'Media', 'Member' => 'Media', 'Office' => 'Media'];
// No null fields: a field missing from a record is null. (Drop this header
// to receive every declared field, nulls included.)
const PREFER = 'Prefer: omit-values=nulls';
/** One HTTP request: [status, headers, body]. */
function http(string $method, string $url, array $headers, ?string $body = null): array
{
$responseHeaders = [];
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_ENCODING => '', // accept gzip
CURLOPT_HEADERFUNCTION => function ($curl, string $line) use (&$responseHeaders): int {
if (str_contains($line, ':')) {
[$name, $value] = explode(':', $line, 2);
$responseHeaders[strtolower(trim($name))] = trim($value);
}
return strlen($line);
},
]);
if ($body !== null) {
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
}
$content = curl_exec($curl);
$status = $content === false ? 0 : (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
return [$status, $responseHeaders, (string) $content];
}
/** A bearer token, reused until one minute before it expires. */
function token(bool $renew = false): string
{
global $root, $clientId, $clientSecret;
static $token = null, $expiresAt = 0;
if (! $renew && $token !== null && time() < $expiresAt - 60) {
return $token;
}
[$status, , $body] = http('POST', "{$root}/api/oauth/token", [
'Authorization: Basic '.base64_encode("{$clientId}:{$clientSecret}"),
'Content-Type: application/x-www-form-urlencoded',
], 'grant_type=client_credentials');
if ($status !== 200) {
throw new RuntimeException("Token request failed: {$status} {$body}");
}
$answer = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
$token = $answer['access_token'];
$expiresAt = time() + $answer['expires_in'];
return $token;
}
/** GET one page. A 401 gets a new token and one more try; 429/503 wait Retry-After; 504 and network errors back off. */
function get(string $url): array
{
$renew = false;
$renewed = false;
for ($attempt = 0; $attempt < 6; $attempt++) {
[$status, $headers, $body] = http('GET', $url, ['Authorization: Bearer '.token($renew), 'Accept: application/json', PREFER]);
$renew = false;
if ($status === 200) {
return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
}
if ($status === 401 && ! $renewed) {
$renew = $renewed = true; // expired or rotated: get a new token, try once more
continue;
}
if ($status === 429 || $status === 503) {
sleep((int) ($headers['retry-after'] ?? 30));
continue;
}
if ($status === 504 || $status === 0) {
sleep(10 * ($attempt + 1));
continue;
}
throw new RuntimeException("{$status} {$body}"); // 400/403/404, a second 401: fix the request
}
throw new RuntimeException("Giving up on {$url}");
}
/**
* Replace with your database write: insert, or update the row with the same feed and key
* (HubFeedKey + key: a key is unique within one feed); replace its stored photo and room lists
* with $record['Media'] / $record['Rooms']. $feeds[HubFeedKey] is the record's feed.
*/
function upsert(string $resource, array $record, array $feeds): void
{
$feed = $feeds[$record['HubFeedKey']]['FeedName'];
$removed = ($record['HubNotSeenInFeedSince'] ?? null) !== null || ($record['HubProviderDeletedAt'] ?? null) !== null;
echo $resource.' '.$feed.' '.$record[KEYS[$resource]].($removed ? ' (removed)' : '').PHP_EOL;
}
/** One run for one resource. Returns the new cursor (the run's @Hub.ReplicationBound). */
/**
* A seek read (guide §4a): the narrowing $filter, seek=true, then the next links as given.
* Returns the read's upper bound (@Hub.ReplicationBound): everything matching up to it was read.
*/
function read(string $resource, array $query, callable $onRecord): ?string
{
global $root;
$query = ['seek' => 'true', '$top' => '100', ...$query];
$url = "{$root}/api/odata/{$resource}?".http_build_query($query, encoding_type: PHP_QUERY_RFC3986);
$bound = null;
while ($url !== null) {
$page = get($url); // an expired next link (400 ExpiredSkipToken) throws: start the read again
foreach ($page['value'] as $record) {
$onRecord($record);
}
$bound = $page['@Hub.ReplicationBound'] ?? $bound;
$url = $page['@odata.nextLink'] ?? null; // follow it exactly as given
}
return $bound;
}
/**
* One run for one resource (guide §4a, use case 1): everything on the first run, then the
* window after the cursor. Returns the new cursor (the run's @Hub.ReplicationBound).
*/
function replicate(string $resource, ?string $cursor, array $feeds): ?string
{
$query = isset(EXPAND[$resource]) ? ['$expand' => EXPAND[$resource]] : [];
if ($cursor !== null) {
$query['$filter'] = "HubModificationTimestamp gt {$cursor}";
}
return read($resource, $query, static fn (array $record) => upsert($resource, $record, $feeds)) ?? $cursor;
}
/** Use case 2: every Active listing of one feed, read consistently while it changes. */
function activeListings(string $feedKey, array $feeds): ?string
{
return read('Property', ['$filter' => "HubFeedKey eq '{$feedKey}' and StandardStatus eq 'Active'"], static fn (array $record) => upsert('Property', $record, $feeds));
}
$state = is_file($stateFile) ? json_decode((string) file_get_contents($stateFile), true) : [];
$granted = array_column(get("{$root}/api/odata/")['value'], 'name');
// Your feeds, once per run: every record names its feed by HubFeedKey.
$feeds = array_column(get("{$root}/api/odata/HubFeed")['value'], null, 'FeedKey');
foreach (array_keys(KEYS) as $resource) {
if (! in_array($resource, $granted, true)) {
continue;
}
$state[$resource] = replicate($resource, $state[$resource] ?? null, $feeds);
// Save after each completed run only: an interrupted run is simply repeated.
file_put_contents($stateFile, json_encode($state, JSON_PRETTY_PRINT));
}
JavaScript (Node.js 18+)#
// A complete Roomvu MLS Hub replication client for Node.js 18+ (built-in fetch, no packages).
//
// Run it on a schedule (for example every 15 minutes). The first run loads
// everything; every later run fetches only what changed since the last run.
//
// HUB_ROOT=https://hub.example.com HUB_CLIENT_ID=hub_... HUB_CLIENT_SECRET=... node replicate.mjs
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
const ROOT = process.env.HUB_ROOT.replace(/\/+$/, '');
const CLIENT_ID = process.env.HUB_CLIENT_ID;
const CLIENT_SECRET = process.env.HUB_CLIENT_SECRET;
const STATE_FILE = process.env.HUB_STATE_FILE ?? 'hub-cursors.json';
// The resources to replicate, the key of each, and what to expand. Photos
// (Media) and rooms come inside their record; Property includes Media by
// default, Member and Office only when asked. Lookup is reference data
// (read it separately).
const KEYS = { Property: 'ListingKey', Member: 'MemberKey', Office: 'OfficeKey', OpenHouse: 'OpenHouseKey' };
const EXPAND = { Property: 'Media', Member: 'Media', Office: 'Media' };
// No null fields: a field missing from a record is null (fetch decompresses gzip by itself).
// Drop the Prefer header to receive every declared field, nulls included.
const PREFER = 'omit-values=nulls';
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
let cached = { value: null, expiresAt: 0 };
// A bearer token, reused until one minute before it expires.
async function token() {
if (cached.value && Date.now() < cached.expiresAt - 60_000) return cached.value;
const response = await fetch(`${ROOT}/api/oauth/token`, {
method: 'POST',
headers: {
Authorization: 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64'),
'Content-Type': 'application/x-www-form-urlencoded',
},
body: 'grant_type=client_credentials',
});
if (!response.ok) throw new Error(`Token request failed: ${response.status} ${await response.text()}`);
const body = await response.json();
cached = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };
return cached.value;
}
// GET one page. A 401 gets a new token and one more try; 429/503 wait Retry-After; 504 and network errors back off.
async function get(url) {
let renewed = false;
for (let attempt = 0; attempt < 6; attempt++) {
let response;
try {
response = await fetch(url, { headers: { Authorization: `Bearer ${await token()}`, Accept: 'application/json', Prefer: PREFER } });
} catch {
await sleep(10 * (attempt + 1)); // network error
continue;
}
if (response.ok) return response.json();
if (response.status === 401 && !renewed) { cached.value = null; renewed = true; continue; } // expired or rotated: once
if (response.status === 429 || response.status === 503) { await sleep(Number(response.headers.get('Retry-After') ?? 30)); continue; }
if (response.status === 504) { await sleep(10 * (attempt + 1)); continue; }
throw new Error(`${response.status} ${await response.text()}`); // 400/403/404, a second 401: fix the request
}
throw new Error(`Giving up on ${url}`);
}
// Replace with your database write: insert, or update the row with the same feed and key
// (HubFeedKey + key: a key is unique within one feed); replace its stored photo and room lists
// with record.Media / record.Rooms. feeds.get(record.HubFeedKey) is the record's feed.
function upsert(resource, record, feeds) {
const feed = feeds.get(record.HubFeedKey).FeedName;
const removed = record.HubNotSeenInFeedSince || record.HubProviderDeletedAt;
console.log(`${resource} ${feed} ${record[KEYS[resource]]}${removed ? ' (removed)' : ''}`);
}
// One run for one resource. Returns the new cursor (the run's @Hub.ReplicationBound).
// A seek read (guide §4a): the narrowing $filter, seek=true, then the next links as given.
// Returns the read's upper bound (@Hub.ReplicationBound): everything matching up to it was read.
async function read(resource, options, onRecord) {
const query = new URLSearchParams({ seek: 'true', $top: '100', ...options });
let url = `${ROOT}/api/odata/${resource}?${query.toString().replaceAll('+', '%20')}`;
let bound = null;
while (url) {
const page = await get(url); // an expired next link (400 ExpiredSkipToken) throws: start the read again
for (const record of page.value) onRecord(record);
bound = page['@Hub.ReplicationBound'] ?? bound;
url = page['@odata.nextLink']; // follow it exactly as given
}
return bound;
}
// One run for one resource (guide §4a, use case 1): everything on the first run, then the
// window after the cursor. Returns the new cursor (the run's @Hub.ReplicationBound).
async function replicate(resource, cursor, feeds) {
const options = EXPAND[resource] ? { $expand: EXPAND[resource] } : {};
if (cursor) options.$filter = `HubModificationTimestamp gt ${cursor}`;
return (await read(resource, options, (record) => upsert(resource, record, feeds))) ?? cursor;
}
// Use case 2: every Active listing of one feed, read consistently while it changes.
async function activeListings(feedKey, feeds) {
return read('Property', { $filter: `HubFeedKey eq '${feedKey}' and StandardStatus eq 'Active'` }, (record) => upsert('Property', record, feeds));
}
const state = existsSync(STATE_FILE) ? JSON.parse(readFileSync(STATE_FILE, 'utf8')) : {};
const granted = new Set((await get(`${ROOT}/api/odata/`)).value.map((entity) => entity.name));
// Your feeds, once per run: every record names its feed by HubFeedKey.
const feeds = new Map((await get(`${ROOT}/api/odata/HubFeed`)).value.map((feed) => [feed.FeedKey, feed]));
for (const resource of Object.keys(KEYS)) {
if (!granted.has(resource)) continue;
state[resource] = await replicate(resource, state[resource] ?? null, feeds);
// Save after each completed run only: an interrupted run is simply repeated.
writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
}
4.10 Checklist for a replicating client#
Before your client goes live, check that it:
- Stores
@Hub.ReplicationBoundas its cursor, per resource, after each completed run — never the largestHubModificationTimestampit received, never its own clock (§4.2). - Sends
Prefer: omit-values=nullson every page, if it reads a missing field asnull— about 40–50 % smaller responses (§4.1). - Reads
HubFeedonce per run for each feed's name, MLS and (with thesourceextension) source name and listing prefix, and identifies every record by (HubFeedKey, key) — never by its key alone (§6.7, §4.4). - Upserts by key and replaces a record's photo and room lists whole; it expects a whole feed again after a feed is granted or resent (§4.6).
- Downloads photos during its run, from the links it just received,
well within a hub link's expiry (72 hours by default,
§7.4) — a listing's photos when its
HubMediaModificationTimestampdiffers from the value it stored, never fromPhotosChangeTimestampalone.
4a. Reading the data: filters and the seek pointer#
Besides replicating everything (§4), a client
often reads one slice: what changed in the last hour, every active
listing, an agent's listings. The seek mode reads such a slice so
that it stays correct while the data changes during the read: add
seek=true to the first request, then follow @odata.nextLink as given.
-
A narrowing filter from a documented set, terms joined by
and(any other field,or,notor a function is refused with400):Resource Seek filters Property HubModificationTimestampgt/ge/lt/le(a time window),StandardStatuseq/in,ListAgentKeyeq,ListOfficeKeyeq,ListingKeyeq/in,ListingIdeq,HubFeedKeyeq/inMember the time window, OfficeKeyeq(an office's agents),MemberKeyeq/in,HubFeedKeyOffice the time window, OfficeKeyeq/in,HubFeedKeyOpenHouse the time window, ListingKeyeq(a listing's open houses),OpenHouseKeyeq/in,HubFeedKey -
A fixed order, chosen by the filter: with a time window,
HubModificationTimestampthen the key (the replication order); with anything else, the key. Do not send$orderbyor$skip: they are refused, because the order is part of how the read continues. -
The seek pointer: each next link carries a signed token holding the last record's ordering values and key and the read's upper bound, fixed at its first page. The next page continues strictly after that record — never by position — so a record added, removed or changed elsewhere never makes another one skipped or repeated.
-
The upper bound (
@Hub.ReplicationBound, on every page of a seek read): the read returns the records as of its start. A record that changes while you read is left out of this read and comes in your next updates read (use case 1) — you never receive one twice in one read and never lose it. -
Token rules: a next link is valid for your client only, unchanged, and for one day (
web_service.seek_token_ttl_seconds); an edited, foreign or expired one is refused with400(InvalidSkipToken,ExpiredSkipToken). OnExpiredSkipToken, start the read again from its first request.
$top, $select, $expand, $count and Prefer: omit-values=nulls
work as everywhere else.
Use case 1: the initial load, then hourly or daily updates#
The initial load is a time window from the beginning:
GET /api/odata/Property?seek=true&$top=100
(no filter at all reads every record in the key order, under the bound
of the first page). Follow the next links; store the last page's
@Hub.ReplicationBound as your cursor. Every hour (or day), read the
window from your cursor up to now:
GET /api/odata/Property?seek=true&$filter=HubModificationTimestamp gt 2026-11-13T08:00:00.123456Z&$top=100
and store the new bound. To read one fixed window — say a day you want to re-check — give both ends:
GET /api/odata/Property?seek=true&$filter=HubModificationTimestamp gt 2026-11-12T00:00:00Z and HubModificationTimestamp le 2026-11-13T00:00:00Z
A window read is a replication run: your grants' modes apply exactly as
in §4.6 (a feed granted after
your cursor arrives whole), and the bound protects against records still
being written (§4.2). Add
HubFeedKey eq '<feed>' to read one feed.
Use case 2: every record in a status#
GET /api/odata/Property?seek=true&$filter=HubFeedKey eq 'spark-sbmls' and StandardStatus eq 'Active'&$top=200
Ordered by the key; follow the next links to the end. A listing whose
status changes while you read is left out of this read (it may no longer
be Active) and arrives in your next updates read with its new status —
read use case 1's window from this read's @Hub.ReplicationBound to
stay current. StandardStatus in ('Active','Pending') reads several.
Use case 3: a member's or an office's records, one record by its key#
GET /api/odata/Property?seek=true&$filter=ListAgentKey eq 'M100'
GET /api/odata/Property?seek=true&$filter=ListOfficeKey eq 'O200'
GET /api/odata/Member?seek=true&$filter=OfficeKey eq 'O200'
GET /api/odata/OpenHouse?seek=true&$filter=ListingKey eq 'X1000001'
GET /api/odata/Property?seek=true&$filter=ListingId eq 'X1000001'
GET /api/odata/Property?seek=true&$filter=ListingKey in ('X1000001','X1000002')
Each in the key order, each continued by its next link. A key is unique
within a feed only: add HubFeedKey eq '<feed>' to read one feed's
record. (The seek mode reads the listing agent and listing office
roles; an agent in any role is the browse request of
§5.4, without the seek pointer.)
Which mode to use#
| You want | Use |
|---|---|
| A complete copy, kept current | §4 replication — or use case 1, the same run with seek=true |
| A slice (a window, a status, an agent's or office's listings) read completely and consistently | the seek mode, use cases 1–3 |
| A quick look: the first page of a search, newest first, a free-text search | a browse request (§5): $orderby, $skip, contains() — fine for one page, not for reading a large set while it changes |
5. Query reference#
5.1 Supported options#
Anything not listed here is refused with 400 and an error naming the
option — never silently ignored.
| Option | Supported | Example |
|---|---|---|
$filter |
eq ne gt ge lt le, and, or, not, parentheses, in (…), null, on the filterable fields below; contains(Field, 'text') on the search fields only |
StandardStatus eq 'Active' and ModificationTimestamp ge 2026-10-01T00:00:00Z; contains(UnparsedAddress, 'oak street') |
$select |
any field of the resource | ListingKey,ListPrice,HubModificationTimestamp |
$expand |
the resource's navigations, or * for all of them; one level, no options inside |
Media,OpenHouses,ListAgent,ListOffice |
$orderby |
HubModificationTimestamp [, <key>] ascending (Property, Member, Office, OpenHouse); ModificationTimestamp asc/desc; the key asc/desc |
ModificationTimestamp desc |
$top |
1 to the maximum (Property 200, others 1,000); default Property 100, others 500 | 100 |
$skip |
browsing only (not on a replication request), up to 10,000 | 200 |
$count |
true → @odata.count; cheap on a replication window or a selective filter (an agent's listings), a full scan of the feed on a broad one (StandardStatus eq 'Active' on a large feed: seconds) — count once, not on every poll |
true |
$skiptoken |
only as found in a next link | — |
seek |
true: the seek mode — a documented narrowing filter, a fixed order, continued only by next links (§4a); $orderby and $skip are refused with it |
seek=true |
$format |
json only |
— |
| by key | Property('<ListingKey>'); HubFeed('<FeedKey>') |
/api/odata/Property('X1000001')?$expand=Media |
Prefer header |
omit-values=nulls: no null-valued property is sent (§4.1) |
Prefer: omit-values=nulls |
5.2 Filterable fields#
Each filterable field is backed by a database index, so every allowed query stays fast.
| Resource | Filterable fields |
|---|---|
| Property | ListingKey, HubFeedKey, ListingId, StandardStatus, PropertyType, ListAgentKey, CoListAgentKey, BuyerAgentKey, CoBuyerAgentKey, ListOfficeKey, CoListOfficeKey, BuyerOfficeKey, CoBuyerOfficeKey, ModificationTimestamp, HubModificationTimestamp, HubNotSeenInFeedSince, HubProviderDeletedAt; search: UnparsedAddress, ListOfficeName |
| Member | MemberKey, HubFeedKey, MemberMlsId, OfficeKey, ModificationTimestamp, HubModificationTimestamp, HubProviderDeletedAt; search: MemberFullName, MemberEmail |
| Office | OfficeKey, HubFeedKey, OfficeMlsId, ModificationTimestamp, HubModificationTimestamp, HubProviderDeletedAt; search: OfficeName |
| OpenHouse | OpenHouseKey, HubFeedKey, ListingKey, OpenHouseDate, ModificationTimestamp, HubModificationTimestamp, HubProviderDeletedAt |
| Media | MediaKey, ResourceRecordKey (the parent's key), ModificationTimestamp |
| Lookup | LookupKey, LookupName, ModificationTimestamp |
| HubFeed | FeedKey |
Operators by field kind:
| Kind | Fields | Operators |
|---|---|---|
| key | ListingKey, MemberKey, …, FeedKey |
eq, in |
| feed | HubFeedKey (a FeedKey of HubFeed, a string: HubFeedKey eq 'spark-sbmls'; a code that is not one of your feeds matches nothing) |
eq, ne, in |
| reference key | a listing's agents and offices (ListAgentKey … CoBuyerOfficeKey), a member's OfficeKey |
eq, ne, in |
| search | UnparsedAddress, ListOfficeName (Property); MemberFullName, MemberEmail (Member); OfficeName (Office) — each on a trigram index |
contains(Field, 'text') only: case-insensitive, anywhere in the value, 3 to 64 characters, at most two per $filter; % and _ are ordinary characters |
| text | ListingId, StandardStatus, PropertyType, MemberMlsId, OfficeMlsId, LookupName |
eq, ne, in |
| timestamp | ModificationTimestamp, HubModificationTimestamp |
eq ne gt ge lt le |
| date | OpenHouseDate |
eq ne gt ge lt le |
| removal marker | HubNotSeenInFeedSince, HubProviderDeletedAt |
eq null, ne null, gt ge lt le |
5.3 Literals#
| Type | Write it as | Example |
|---|---|---|
| text | single quotes; a quote inside is doubled | 'Active', 'O''Brien' |
| timestamp | ISO 8601, UTC Z or an offset, fractions allowed |
2026-10-10T12:00:00Z, 2026-10-10T12:00:00.123456Z |
| date | YYYY-MM-DD, a real calendar date |
2026-10-10 |
| null, boolean | bare | null, true, false |
5.4 Examples#
| Question | Request |
|---|---|
| One listing with photos and rooms | GET /api/odata/Property('X1000001') |
| A listing by its MLS number | GET /api/odata/Property?$filter=ListingId eq 'X1000001' |
| Several listings at once | GET /api/odata/Property?$filter=ListingKey in ('X1000001','X1000002') |
| Active listings, newest change first | GET /api/odata/Property?$filter=StandardStatus eq 'Active'&$orderby=ModificationTimestamp desc |
| A listing's agent and office | GET /api/odata/Property('X1000001')?$expand=ListAgent,ListOffice&$select=ListingKey,ListAgent,ListOffice |
| An agent by MLS id | GET /api/odata/Member?$filter=MemberMlsId eq 'A12345' |
| Listings whose address contains a text | GET /api/odata/Property?$filter=contains(UnparsedAddress, 'oak street') |
| Agents by part of their name, in one feed | GET /api/odata/Member?$filter=HubFeedKey eq 'spark-sbmls' and contains(MemberFullName, 'agent') |
| One feed's listings | GET /api/odata/Property?$filter=HubFeedKey eq 'spark-sbmls' |
| One listing of one feed (a key is unique only within a feed) | GET /api/odata/Property?$filter=HubFeedKey eq 'spark-sbmls' and ListingKey eq 'X1000001' |
| An agent's listings, in any role | GET /api/odata/Property?$filter=HubFeedKey eq 'spark-sbmls' and (ListAgentKey eq 'M100' or CoListAgentKey eq 'M100' or BuyerAgentKey eq 'M100' or CoBuyerAgentKey eq 'M100') |
| An office's listings as listing office | GET /api/odata/Property?$filter=HubFeedKey eq 'spark-sbmls' and ListOfficeKey eq 'O200' |
| An office's agents | GET /api/odata/Member?$filter=HubFeedKey eq 'spark-sbmls' and OfficeKey eq 'O200' |
| Next week's open houses | GET /api/odata/OpenHouse?$filter=OpenHouseDate ge 2026-10-12 and OpenHouseDate le 2026-10-18 |
| Open houses of one listing | GET /api/odata/OpenHouse?$filter=ListingKey eq 'X1000001' |
| Photos of one record | GET /api/odata/Media?$filter=ResourceRecordKey eq 'X1000001' |
| How many listings | GET /api/odata/Property?$count=true&$top=1 |
| Removed listings | GET /api/odata/Property?$filter=HubNotSeenInFeedSince ne null |
| The values of one lookup | GET /api/odata/Lookup?$filter=LookupName eq 'StandardStatus' |
5.5 What is refused, and why#
| Refused | Why | Do instead |
|---|---|---|
$filter on any other field (price, city, bedrooms, dates…) |
Only indexed fields are filterable, so no query can scan millions of rows. | Replicate and filter in your own database. |
contains() on any field but the five search fields; startswith, now(), year() and every other function, has, any/all, $search, $apply |
Outside the supported subset; a search field has a trigram index, nothing else does. | Filter on your side. |
Options inside $expand (Media($select=…)), or a navigation of an expanded record (ListAgent/Office, ListAgent($expand=Office)) |
$expand is one level, without options. |
Expand plainly; replicate Member and Office and join by key. |
$skip on a replication request |
Offsets miss or repeat rows when data changes between pages. | Follow @odata.nextLink. |
$skip above 10,000 |
Deep offsets are slow. | Replicate with the cursor. |
$orderby on any other field |
Every order must be served by an index. | Sort on your side. |
$top above the maximum |
Pages stay a reasonable size. | Use the maximum and follow next links. |
A $filter longer than 8,000 characters, with more than 200 comparisons, or nested deeper than 16 levels; an in list longer than 500 values |
Protects the service. | Split the request; use in (…) instead of long or chains. |
| A next link of another client, or an edited one | Next links are signed for you. | Follow your own next links unchanged. |
With seek=true: $orderby, $skip, a field outside the seek filters, or/not/a function; a seek next link older than a day |
The order is part of how the read continues; the bound of an old read is stale. | Use the seek filters (§4a); start the read again. |
5.6 Defaults worth knowing#
- Property includes
Mediaby default (as Bridge does). To leave the photos out, name$expandwithoutMedia, or$selectfields withoutMedia. Member and Office don't: ask with$expand=Media. - Without
$orderby, records come in a stable order (by feed, then key). - Every declared field is present in every record; an empty one is
null— unless you sendPrefer: omit-values=nulls(§4.1), then a missing field isnull. - A field your client is not served is neither selectable, filterable nor orderable.
6. Resources and fields#
The full list of fields, with their types and RESO definitions, is the
field reference, generated from
$metadata so it always matches the service. Your own $metadata is
the final word for your client.
| Resource | What it is | Key | Navigations (for $expand) |
|---|---|---|---|
| Property | A listing | ListingKey |
Media (default), OpenHouses, ListAgent, CoListAgent, BuyerAgent, CoBuyerAgent, ListOffice, CoListOffice, BuyerOffice, CoBuyerOffice |
| Member | An agent | MemberKey |
Media (the agent's photo), Office |
| Office | An office | OfficeKey |
Media (logo, photos), MainOffice |
| OpenHouse | An open house | OpenHouseKey |
Listing |
| Media | A photo, video or document | MediaKey |
— |
| Lookup | The allowed values of the lookup fields | LookupKey |
— |
| HubFeed | Your feeds (the hub's own set, not RESO) | FeedKey |
— |
Rooms are not a resource: $metadata declares PropertyRooms as a
complex type without a key, and Property's Rooms property as a
collection of it, present in every listing ([] when it has none). Many
feeds send rooms without a key, so RoomKey is an ordinary field and can
be null. Store a listing's rooms as a list that each arrival replaces,
never keyed by RoomKey.
6.1 Types#
| RESO type | OData type | In JSON |
|---|---|---|
| String | Edm.String |
"Sampletown" |
| Lookup, single | Edm.String |
"Active" |
| Lookup, multiple | Collection(Edm.String) |
["Fireplace", "Garage"] |
| Boolean | Edm.Boolean |
true |
Number, whole (the fields the DD defines as integers: BathroomsTotalInteger, StreetNumberNumeric, Media Order; and ListingKeyNumeric) |
Edm.Int64 |
3 |
| Number, any other | Edm.Decimal |
3, 1.5, 649900 — never 3.0000 |
| Date | Edm.Date |
"2026-10-10" |
| Timestamp | Edm.DateTimeOffset |
"2026-10-10T14:03:22Z" (UTC) |
Why most numbers are Edm.Decimal: the RESO Data Dictionary gives no
precision for counts such as BedroomsTotal or Stories, and feeds do
send fractions (Stories 1.5). The hub keeps them exact. Read them as
JSON numbers.
6.2 Property#
An excerpt of one listing (invented values; a real record carries every
field of your $metadata, null when empty):
{
"ListingKey": "X1000001",
"ListingId": "X1000001",
"StandardStatus": "Active",
"PropertyType": "Residential",
"PropertySubType": "SingleFamilyResidence",
"ListPrice": 649900,
"BedroomsTotal": 3,
"BathroomsTotalInteger": 2,
"LivingArea": 1850,
"LivingAreaUnits": "SquareFeet",
"StreetNumber": "123",
"StreetName": "SAMPLE",
"StreetSuffix": "ST",
"UnparsedAddress": "123 Sample Street",
"City": "Sampletown",
"StateOrProvince": "ON",
"PostalCode": "A1A 1A1",
"Country": "CA",
"InteriorFeatures": ["Fireplace"],
"ListAgentKey": "M5550001",
"ListAgentFullName": "Jane Q Agent",
"ListAgentDirectPhone": "+14165550142",
"ListOfficeKey": "O5550001",
"ListOfficeName": "Sample Realty Inc.",
"PhotosCount": 1,
"PhotosChangeTimestamp": "2026-10-09T15:00:00Z",
"ModificationTimestamp": "2026-10-09T15:00:00Z",
"HubFeedKey": "sample-feed",
"HubModificationTimestamp": "2026-10-09T15:00:04.512345Z",
"HubNotSeenInFeedSince": null,
"HubProviderDeletedAt": null,
"HubMediaModificationTimestamp": "2026-10-09T15:00:04.512345Z",
"Media": [
{
"MediaKey": "P1000001-1",
"ResourceRecordKey": "X1000001",
"ResourceName": "Property",
"MediaCategory": "Photo",
"MediaType": "jpeg",
"Order": 1,
"MediaURL": "https://photos.example.com/X1000001/1.jpg",
"MediaModificationTimestamp": "2026-10-09T14:58:00Z"
}
]
}
HubMediaModificationTimestamp (Edm.DateTimeOffset, UTC,
microseconds; nullable) is the moment the hub's stored Media list of
this listing last changed: an item added, changed, reordered or removed.
It is the hub's own fact, not the MLS's — the MLS's
PhotosChangeTimestamp is served beside it, untouched. It is null while
the hub never stored a photo for the listing; it does not move when the
hub reads the listing again and finds the same list; and it is never later
than HubModificationTimestamp, which moves with it (the two are equal
when the listing's last change was its photos). It is on Property only,
and it is not filterable: every change of it reaches you through the
HubModificationTimestamp cursor. How to use it:
§7.4.
ListingKeyNumeric (Edm.Int64, the last RESO field of a listing,
before the Hub… ones) is the numeric form of the listing's key where
the MLS's system sends one, exactly as sent: on some feeds a number of
its own beside a ListingKey that is not numeric, on others the same
digits as ListingKey, and null on every feed whose system has no such
field. The hub never fills it from ListingKey. It comes from RESO Data
Dictionary 1.7; the Data Dictionary 2.0 has no such field, so do not
expect it from every feed. A record's identity is still
(HubFeedKey, ListingKey) (§4.4); ListingKeyNumeric
is for a system that already identifies a feed's listings by that number.
It is not filterable.
6.3 Member and Office#
{
"MemberKey": "M5550001",
"MemberMlsId": "A12345",
"MemberFirstName": "Jane",
"MemberLastName": "Agent",
"MemberFullName": "Jane Q Agent",
"MemberEmail": "jane.agent@example.com",
"MemberDirectPhone": "+14165550142",
"MemberStatus": "Active",
"OfficeKey": "O5550001",
"OfficeName": "Sample Realty Inc.",
"ModificationTimestamp": "2026-09-30T10:00:00Z",
"HubFeedKey": "sample-feed",
"HubModificationTimestamp": "2026-09-30T10:00:02.000001Z",
"HubProviderDeletedAt": null
}
{
"OfficeKey": "O5550001",
"OfficeMlsId": "SMPL01",
"OfficeName": "Sample Realty Inc.",
"OfficePhone": "+14165550100",
"OfficeAddress1": "1 Example Avenue",
"OfficeCity": "Sampletown",
"OfficeStateOrProvince": "ON",
"OfficePostalCode": "A1A 1A1",
"OfficeStatus": "Active",
"MainOfficeKey": "O5550001",
"ModificationTimestamp": "2026-09-01T09:00:00Z",
"HubFeedKey": "sample-feed",
"HubModificationTimestamp": "2026-09-01T09:00:01.250000Z",
"HubProviderDeletedAt": null
}
6.4 OpenHouse#
{
"OpenHouseKey": "OH-77001",
"ListingKey": "X1000001",
"OpenHouseDate": "2026-10-12",
"OpenHouseStartTime": "2026-10-12T14:00:00-04:00",
"OpenHouseEndTime": "2026-10-12T16:00:00-04:00",
"HubOpenHouseLocalStartTime": "2026-10-12T14:00:00",
"HubOpenHouseLocalEndTime": "2026-10-12T16:00:00",
"OpenHouseStatus": "Active",
"OpenHouseType": "Public",
"ModificationTimestamp": "2026-10-08T11:00:00Z",
"HubFeedKey": "sample-feed",
"HubModificationTimestamp": "2026-10-08T11:00:03.000002Z",
"HubProviderDeletedAt": null
}
Open-house times are the one place where time zones matter:
HubOpenHouseLocalStartTime/HubOpenHouseLocalEndTimealways hold the local wall-clock time as the MLS sent it, without a zone (2026-10-12T14:00:00= 2 pm where the house is).OpenHouseStartTime/OpenHouseEndTimecarry the same moment with its offset — but only for feeds whose time zone the hub knows. For other feeds they arenull; use the local pair. The hub never guesses a zone.
6.5 Media#
{
"MediaKey": "P1000001-1",
"ResourceRecordKey": "X1000001",
"ResourceName": "Property",
"MediaCategory": "Photo",
"MediaType": "jpeg",
"Order": 1,
"MediaURL": "https://photos.example.com/X1000001/1.jpg",
"ShortDescription": "Front of the house",
"MediaModificationTimestamp": "2026-10-09T14:58:00Z",
"ModificationTimestamp": "2026-10-09T14:58:00Z"
}
Values are as the feed sent them: MediaType may be jpeg, Jpeg or
image/jpeg depending on the feed, and fields such as ResourceName or
MediaModificationTimestamp are often null. See §7 for what
MediaURL points to and how long it lives.
6.6 Lookup#
The Lookup resource lists the values each lookup field can carry: the
RESO standard values, and the MLS's own local values where a field is
open to them. Read it when you build your value lists, and again from
time to time (new local values can appear).
{
"LookupKey": "1705",
"LookupName": "StandardStatus",
"LookupValue": "ActiveUnderContract",
"StandardLookupValue": "Active Under Contract",
"LegacyODataValue": "ActiveUnderContract",
"ModificationTimestamp": "2026-10-01T00:00:00Z"
}
LookupValueis what appears in the records.StandardLookupValueis the RESO display name; it is empty for a local value (one the MLS uses that RESO does not define).- Local values are listed only from the feeds, resources and fields you are granted.
Lookuphas no replication cursor. It is small (a few thousand rows): read it whole when you start, then once a day — or ask only for what changed with$filter=ModificationTimestamp gt <your last read>.
GET /api/odata/Lookup?$filter=LookupName eq 'PropertySubType'
6.7 HubFeed#
Your feeds, one row each — the hub's own entity set, not RESO, so its
name starts with Hub. Every listing, agent, office and open house
names its feed in HubFeedKey.
{
"FeedKey": "sample-feed",
"FeedName": "Sample Feed",
"ProviderName": "Sample Provider",
"OriginMlsName": "Sample Board of REALTORS",
"OriginMlsUoi": "M00099999"
}
FeedKeyis the feed's code (provider-dataset, lowercase, hyphens, at most 32 characters). It never changes and is never reused: a feed that is retired keeps its code forever.OriginMlsName/OriginMlsUoiname the MLS when the whole feed is one MLS; they arenullfor a feed that carries several boards (CREA's national pool) — ask for theorigin_mlsextension to get it per record.- With the
sourceextension each row also hasSourceNameandListingPrefix(the old Roomvu platform's names for the feed). - It is small (a few dozen rows): read it whole once per run. A feed you are no longer granted disappears from it.
GET /api/odata/HubFeed
6.8 Provider metadata#
The data above is the hub's uniform RESO view of every feed. Each feed
also has its provider's OWN vocabulary: the fields the provider
declares, their types and labels, and its lookup values exactly as its
records carry them. Read it when you need to know what a local value
means, what a field in HubExtraFields is, or which of the provider's
fields a RESO field comes from.
It is a service root of its own, https://mlshub.roomvu.com/api/provider-metadata/,
with the same token, allowed IPs and rate limit as the data. It serves
two RESO Data Dictionary resources, for your granted feeds only:
{
"FieldKey": "sample-feed:812",
"ResourceName": "Property",
"FieldName": "Status",
"ModificationTimestamp": "2026-11-13T05:07:00Z",
"HubFeedKey": "sample-feed",
"HubDataType": "Edm.String",
"HubMaxLength": 50,
"HubPrecision": null,
"HubScale": null,
"HubCollection": false,
"HubLookupName": "ListingStatus",
"HubDisplayName": "Listing status",
"HubProviderStandardName": null,
"HubStandardResourceName": "Property",
"HubStandardFieldName": "StandardStatus"
}
{
"LookupKey": "sample-feed:4410",
"LookupName": "ListingStatus",
"LookupValue": "Under Contract",
"StandardLookupValue": "Pending",
"LegacyODataValue": null,
"ModificationTimestamp": "2026-11-13T05:07:00Z",
"HubFeedKey": "sample-feed",
"HubDeclaredCode": null,
"HubDeclaredShortValue": null
}
ResourceName,FieldName,LookupNameandLookupValueare the provider's own, exactly as it declares them (a RETS provider's resource isResource:Class, e.g.Property:RES, and its lookups are namedResource:LookupName).HubStandardResourceName/HubStandardFieldName: the RESO field the hub fills from this field (null: none).StandardLookupValue: the RESO value this value becomes in the data (null: a local value, served as sent).HubDeclaredCode/HubDeclaredShortValue: a RETS lookup's coded value and short value, as declared.- It is refreshed from the provider at most daily;
ModificationTimestampmoves only when a row changes. Ask for what changed with$filter=ModificationTimestamp gt <your last read>. A feed whose metadata the hub has not read yet simply has no rows. $filtertakesHubFeedKey,ResourceName,FieldName(Field),LookupName(Lookup) witheqorin, andModificationTimestampwithgtorge, joined byand; also$select,$top(at most 1,000) and$count. Follow@odata.nextLinkfor the next page. Anything else is a400. Its$metadatais athttps://mlshub.roomvu.com/api/provider-metadata/$metadata, its OpenAPI description athttps://mlshub.roomvu.com/api/docs/provider-metadata.openapi.json.
GET /api/provider-metadata/Lookup?$filter=HubFeedKey eq 'sample-feed' and LookupName eq 'ListingStatus'
GET /api/provider-metadata/Field?$filter=HubFeedKey eq 'sample-feed' and ResourceName eq 'Property'
7. Media#
7.1 What MediaURL points to#
MediaURL is where the item's bytes are. It is one of:
-
The MLS's own link (most feeds). Served exactly as stored; it follows that MLS's rules (some expire after a while; read the record again for its current link).
-
A signed hub link, for photos the hub fetches itself (feeds that only offer photos through an authenticated download):
https://mlshub.roomvu.com/media/12:34407421/34407421.jpg?c=7&e=1791900000&s=9f2c…
A hub link uses the service root's scheme and host (HTTPS in production;
http:// only on a local test server).
The MLS's own links are served exactly as the feed sent them, so they
vary: most are HTTPS image links, some are http://, and for some
categories they are not a direct download at all. A virtual tour
(MediaCategory such as UnbrandedVirtualTour) can be a web page, a bare
domain, or even an HTML snippet the feed put there; a video or document
can have no MediaURL. Check the category and the value before
downloading.
Treat a hub link as opaque: which kind a feed uses can change, and the field stays the same.
7.2 Expiry of hub links#
A signed hub link is valid for 72 hours by default (your
administrator can change it for your client), only for your client, and
only while you are still granted that feed. An expired, edited or foreign
link answers 404. For a fresh link, read the record again.
7.3 Rate limits#
Photo downloads through hub links are limited per client (600 a minute by
default) and answer 429 with Retry-After above it. A photo the hub has
to fetch from the MLS may answer 503 with Retry-After when that MLS's
hourly allowance is used up — retry after the indicated time. Photo links
answer with a short plain-text body, not the OData error object: 404
(expired, edited, not yours, or no such photo), 429 and 503 (wait
Retry-After seconds).
7.4 When to download#
Download the photos during your replication run, from the links in the records you just received. The 72-hour lifetime covers a daily cycle plus a retry the next day.
The rule for a listing: re-download its photos when
HubMediaModificationTimestamp changes. Store the value with the
listing. When the listing arrives again:
- the same value — the photo list you hold is the current one; the listing came for another reason (a price, a status, a room). Download nothing.
- a different value (or a value where you stored
null) — the list changed: replace your stored list with theMediaarray received and fetch what is new in it (below). null— the hub never stored a photo for this listing; itsMediaarray is empty.
The value and the list always arrive together: the hub writes both in one transaction, so a record that shows a new value carries the new list.
Never decide from the MLS's PhotosChangeTimestamp alone. It is the
MLS's own statement, served as sent: not every feed sends it, and on some
feeds the photos reach the hub a moment after the listing that announced
them — a listing can arrive with a new PhotosChangeTimestamp and still
the old list, and arrive again (its HubMediaModificationTimestamp moved)
once the hub holds the new one. HubMediaModificationTimestamp describes
the list you are actually given.
When a record arrives, its Media array is the complete current list:
photos missing from it were removed (§7.5). To decide which files to download
from a changed list, compare by MediaKey and MediaURL with what you
stored: a new key, or a known key with a new URL, is a photo to fetch.
Many feeds leave MediaModificationTimestamp empty, so don't rely on it
alone; use it when it is set. An agent's or an office's photos have no
such timestamp: compare their list the same way whenever the record
arrives.
7.5 Deleted photos#
A record's Media list never contains an item the MLS deleted. When
the MLS deletes a photo, video or document, it leaves the record's
Media list, the Media entity set and every $expand=Media answer
together, and the record's HubModificationTimestamp moves, so your next
replication run receives the record with its current list. Replacing your
stored list with the one received (§4.5)
is all you need to do; there is no "deleted" marker to read and nothing
to filter.
An item is removed only on the MLS's own statement:
- it marks the item deleted (a deleted status or flag on the item), or lists it in its feed of deletions; or
- it sends the record's complete media list and the item is no longer in it.
Nothing weaker removes an item: not a list the MLS sent only in part, not a download that failed, not a link that stopped answering.
What this means for you:
- Hub links stop at once. A signed hub link to a removed item answers
404, even if it has not expired. An MLS's own link is no longer given to you; whether that address still answers is up to the MLS — delete your copy when the item leaves the list. - As of the record's timestamp. The list is the MLS's list as of the
record's
HubModificationTimestamp. A deletion reaches you after the MLS reports it to the hub and your next run reads the record. MediaStatusis never the deleted status. Where a feed sends a status, it is served as sent (Active,Processing…); most feeds send none (null). An item with a deleted status is never served.- A deleted listing is a different signal. When the listing itself is
deleted or leaves its feed, that is said on the listing
(
HubProviderDeletedAt,HubNotSeenInFeedSince); itsMedialist stays as the MLS last sent it.
8. Errors and rate limits#
Every error of the OData endpoints is an OData error object:
{ "error": { "code": "NotSupported", "message": "Query option [$search] is not supported. Supported: $filter, $select, …" } }
| Status | code |
When | What to do |
|---|---|---|---|
| 400 | NotSupported |
an option, field or shape outside the subset (§5.5) | Change the request; the message names the problem. Don't retry as is. |
| 400 | InvalidFilter, InvalidSelect, InvalidExpand, InvalidOrderBy, InvalidTop, InvalidSkip |
a syntax error, an unknown name, a bad literal or an out-of-range value | Fix the request. |
| 400 | InvalidSkipToken |
an edited next link, or one issued to another client or entity set | Follow your own next links unchanged; restart the run from your cursor. |
| 401 | Unauthorized |
no token, an expired or revoked token | Get a new token and retry once. If the token request answers invalid_client, your secret was rotated or your client revoked: contact the administrator. |
| 403 | Forbidden |
a resource your client is not granted | Ask the administrator, or stop requesting it. |
| 403 | IpNotAllowed |
your address is not in the client's allowed IP list (§3.7); the message names the address the hub saw | Call from an allowed address, or add it to the list in the client portal. Don't retry as is. |
| 404 | NotFound |
an unknown entity set, or a key that doesn't exist or isn't in your feeds | Treat it as "no such record for you". |
| 429 | TooManyRequests |
over your client's request rate | Wait Retry-After seconds, then continue. |
| 503 | MediaLinksUnavailable |
the service cannot sign photo links at the moment (a configuration problem on our side) | Retry later and tell the administrator. |
| 504 | QueryTimeout |
the query ran longer than 20 seconds | Retry with a smaller $top or a narrower filter. |
| 500 | InternalError |
a failure on the service's side | Retry later; report it if it repeats. |
Rate limits:
| Default | Above it | |
|---|---|---|
| OData requests | 300 a minute per client | 429 + Retry-After |
| Photo downloads (hub links) | 600 a minute per client | 429 + Retry-After |
| Token requests | 10 a minute per address | 429 + Retry-After |
| Query time | 20 seconds | 504 |
The request and photo limits are set per client; ask the administrator
if yours need to be higher. The OData responses carry no rate-limit
headers: pace yourself (a sequential client following next links stays
far below 300 a minute) and wait Retry-After seconds on a 429.
An unexpected failure on the service's side is a 500 with code
InternalError and no detail; retry later, and tell the administrator if
it repeats. Network errors and 5xx answers can be
retried with a growing pause (10 s, 20 s, 30 s…).
9. Extensions#
Ask the administrator to switch on the extensions you need. Each adds
Hub fields to your $metadata and your data.
| Extension | Adds | Use it for |
|---|---|---|
source |
SourceName, ListingPrefix on your HubFeed rows |
The old Roomvu platform's source name and listing-id prefix of each feed (ListingPrefix is null for feeds without one). Never on the records: join by HubFeedKey. |
origin_mls |
HubOriginMlsName, HubOriginMlsUoi on every Property, Member, Office and OpenHouse |
The association (board) each record belongs to — what you need on a feed that carries several boards, such as CREA. A one-MLS feed's MLS is on its HubFeed row for every client. |
synthetic |
Member and Office rows the hub built from a listing's agent/office fields, flagged HubIsSynthetic: true |
Agents and offices of feeds that send no agent records. Hidden without it. |
extra_fields |
HubExtraFields: the feed's raw fields with no RESO home, as one JSON object (an open complex type: the MLS's own names, each value in the JSON type it sent) |
Listing data the RESO Dictionary has no field for. Raw names and values, as the MLS sent them; which names a record carries depends on its feed. Never the protocol's annotations (@odata.id …), the feed's delivery envelope (its system timestamps, feed grants, platform ids) or a copy of a RESO field the record already carries. Some of it is for professionals only (§2.7). |
Example: a CREA listing with origin_mls (excerpt), and its feed's row in
HubFeed with source:
{
"ListingKey": "X1000001",
"HubFeedKey": "crea-ddf",
"HubOriginMlsName": "Sample Board of REALTORS",
"HubOriginMlsUoi": "M00099999"
}
{
"FeedKey": "crea-ddf",
"FeedName": "CREA",
"ProviderName": "CREA DDF Web API",
"OriginMlsName": null,
"OriginMlsUoi": null,
"SourceName": "crea",
"ListingPrefix": null
}
With extra_fields, a listing's raw fields are one JSON object — parse
the page once, never a string inside it:
{
"ListingKey": "X1000001",
"HubExtraFields": { "SAMPLE_LocalCode": "A7", "SAMPLE_Count": 3, "SAMPLE_Flags": ["x", "y"] }
}
10. Compatibility and versioning#
The output is frozen from the first client on: after that, only additive changes. New feeds and fields are added over time, without notice, while you replicate. They never break your client:
May change without notice (additions only):
- new feeds in your data (when granted to you), and new records;
- new local values on open lookups (listed in
Lookup); - values in fields that were empty so far;
- new extension fields inside an extension you have, a new extension or navigation offered to you, a new filterable field;
- which kind of
MediaURLa feed uses (§7.1).
Never changes on this service root:
- the name, type, precision or nullability of a served field, a navigation or an entity set;
- the meaning of the cursor, the removal markers and the feed key;
- a field or resource you are served disappearing;
- the defaults: every declared field present (nulls included) unless you
ask otherwise, Media included on Property,
$expandone level.
So: ignore properties you don't know (the OData rule), read lookup
values as open lists, and treat MediaURL as opaque.
If a breaking change were ever needed (none is planned), it would come as
a new, versioned service root (/api/odata/v2/…) beside this one,
announced in advance with a date in the changelog; your
cursor would carry over unchanged.
11. FAQ#
Why does the same house (or agent) appear twice? It comes through two
feeds (for example TRREB and CREA's national pool, or several feeds of
one dataset). Each copy is served with its own feed and key
(HubFeedKey). The hub never merges them, and it does not
serve its own guesses about which listings are the same.
Which feed is this record from? HubFeedKey names a row of
HubFeed (its name, provider, MLS). Read HubFeed once per run.
Can I filter by price, city or bedrooms? No — only the indexed fields of §5.2. Replicate, then query your own copy.
Can I replicate only active listings? Don't: with a status filter you
would never learn that a listing closed or was withdrawn. Replicate
everything and filter on your side. For a quick look, a browse request
($filter=StandardStatus eq 'Active') is fine.
Why not use ModificationTimestamp as my cursor? Each MLS sets it
with its own clock and rules, and it does not move when photos change.
HubModificationTimestamp is one clock across every feed and covers
photos and rooms.
My poll suddenly returned a whole feed. Why? A feed was granted to you in full mode, or resent. Upsert as usual.
A listing disappeared from the MLS website but is still Active here.
Some feeds never say when a listing leaves. For those the hub checks
regularly and sets HubNotSeenInFeedSince; other feeds send the closing
status themselves. The hub never sets a status on its own.
Why is OpenHouseStartTime null? That feed spans several time zones
and its open houses carry none (CREA), so the hub can't give the time an
offset. Use HubOpenHouseLocalStartTime (local wall-clock time).
Where are the rooms? In every listing's Rooms property (no
$expand needed — $expand=Rooms is refused, it is not a navigation).
How do I find a listing's agent? ListAgentKey names a Member of
the same feed: look it up in your replicated Members by (HubFeedKey,
ListAgentKey). $expand=ListAgent shows it inline for a few listings.
The listing also carries the agent's name and phone in its own
ListAgent… fields.
Which time zone are timestamps in? UTC, always — except the local open-house pair above.
Do I need to read $metadata? Yes, when you build your mapping and
from time to time after. It lists exactly your fields; new ones can
appear (§10).
How fast can I poll? Every few minutes is fine; 15 minutes is a good default. Stay under your request limit (§8).
A key I stored no longer exists (404). The feed may have been taken
away from your client. Records are never deleted while you are granted
their feed; removals arrive as markers (§2.4).
Should I replicate Media or Lookup separately? Media no: photos
come inside their records (§4.5).
Lookup yes, as reference data, daily (§6.6).
Why does a key in a listing answer 404? References are optional
links (§4.8).
Are responses compressed? Yes, when you send Accept-Encoding: gzip.
Can the pages be smaller? Send Prefer: omit-values=nulls: null
fields are left out (most fields of most records are empty), and a
missing field means null. The response confirms it with
Preference-Applied: omit-values=nulls. Send the header on every page.
Is there an OpenAPI description? Yes:
openapi.json and Swagger
UI, converted from $metadata with the OASIS
standard converter. It describes the OData paths; the token endpoint
appears as its OAuth2 security scheme. $metadata stays the contract.
12. Changelog#
| Date | Change |
|---|---|
| 2026-11-19 | New field (additive): HubMediaModificationTimestamp on Property — Edm.DateTimeOffset (UTC, microseconds), nullable, a base field every client gets, after HubProviderDeletedAt: when the hub's stored Media list of the listing last changed (an item added, changed, reordered or removed); null while no photo was ever stored; unchanged when the hub reads the same list again; never later than HubModificationTimestamp, which moves with it. Rule: re-download a listing's photos when this value changes, never from PhotosChangeTimestamp alone (§7.4, §6.2). Listings stored before this date carry the time their stored photos were last written, and came once more through the cursor with it. Not filterable. In $metadata, the field reference and the OpenAPI description. No existing field changed or moved. |
| 2026-11-17 | New field (additive): ListingKeyNumeric on Property — Edm.Int64, nullable, declared after the other RESO fields: the numeric form of the listing's key where the MLS's system sends one, exactly as sent, null on every other feed and never filled from ListingKey (§6.2). In $metadata, the field reference and the OpenAPI description. No existing field changed or moved. |
| 2026-11-13 | New (additive): each provider's own metadata. A service root of its own, /api/provider-metadata/, serves the RESO Data Dictionary Field and Lookup resources of your granted feeds: the fields each feed's provider declares (its names, types, labels, lookups) and its lookup values exactly as its records carry them, each with the RESO field / standard value the hub maps it to (§6.8); its own OpenAPI description beside the main one. The main service, its $metadata and its Lookup are unchanged. |
| 2026-11-17 | Guarantee stated (no change to the schema): a record's Media list never contains an item the MLS deleted, for every feed — by the MLS's deleted status or flag, its feed of deletions, or the item missing from a complete list it sent; a hub link to a removed item answers 404 at once (§7.5). |
| 2026-11-13 | New (additive): the seek mode. seek=true reads a slice — a HubModificationTimestamp window, a status, an agent's or office's listings, an office's agents, a listing's open houses, records by key or ListingId, each with HubFeedKey — in an order fixed by its filter, continued only by @odata.nextLink (a signed token: the last record's ordering values and key and the read's upper bound, valid for a day): stable while the data changes (§4a). New errors with it: InvalidSeek, ExpiredSkipToken. Requests without seek=true behave exactly as before. The portal's data browser offers it as the order "Seek pointer". |
| 2026-10-11 | New (additive): free-text search. contains(Field, 'text') in $filter on UnparsedAddress and ListOfficeName (Property), MemberFullName and MemberEmail (Member), OfficeName (Office): case-insensitive, anywhere in the value, 3 to 64 characters, at most two per $filter, each on its own index (§5.2, §5.4). The portal's data browser offers the same boxes. No field changed. |
| 2026-10-11 | Changed (the feed key, final — before the first client): HubFeedKey and HubFeed.FeedKey are strings — the feed's code, provider-dataset (spark-sbmls, bridge-nabor, proptx-trreb, crea-ddf; lowercase, hyphens, at most 32 characters), never a number: HubFeedKey eq 'spark-sbmls', HubFeed('spark-sbmls'). A code never changes and is never reused. A feed is one dataset of one provider; several credentials may feed one feed (§2.1). |
| 2026-10-11 | New filterable fields (additive; each backed by an index): HubFeedKey on Property, Member, Office and OpenHouse (one feed's records; eq, ne, in); a listing's ListAgentKey, CoListAgentKey, BuyerAgentKey, CoBuyerAgentKey, ListOfficeKey, CoListOfficeKey, BuyerOfficeKey, CoBuyerOfficeKey (an agent's or an office's listings) and a member's OfficeKey (an office's agents) — eq, ne, in (§5.2, §5.4). New: the portal's data browser — your data through the API, with the request behind each page. No field changed. |
| 2026-10-11 | New: the client portal — your feeds with counts and freshness, 30 days of usage, a data preview identical to the API's answer, your security log; your own allowed IPs, secret rotation (normal or "may be compromised") and token revocation. New: allowed IP addresses (§3.7) — empty by default (nothing changes for you); when set, a request from another address gets 403 (access_denied at the token endpoint, IpNotAllowed elsewhere). Additive; no field changed. |
| 2026-10-11 | Changed (before the first client): HubExtraFields carries only listing data with no RESO home — the protocol's annotations (@odata.id, …@Core.Permissions), the feed's envelope (system timestamps, feed grants, platform ids) and copies of RESO fields (Coordinates, BathroomsTotalDecimal …) are no longer in it; a room's ListingKey/ListingId and a photo's ResourceRecordKey/ResourceRecordID are always their listing's (or member's, office's) own, an open house's ListingId its listing's; a unit field (FarmLandAreaUnits, LotSizeUnits …) is served only beside its value; an age range (51-99 Years) is no longer a PropertyCondition. New: §2.7 — data meant for professionals, and the display rules a public site applies itself. |
| 2026-10-11 | Output review before the first client (the last change that is not additive). New: the HubFeed entity set (your feeds: name, provider, MLS; SourceName and ListingPrefix with source) and HubFeedKey on every Property, Member, Office and OpenHouse; Prefer: omit-values=nulls. Changed: HubExtraFields is a JSON object, no longer a JSON string; $expand is one level (a navigation of an expanded record or an option inside $expand is refused) and an expanded listing carries its Rooms. Removed: HubSourceName, HubListingPrefix, HubAccessName, HubProviderName (now on HubFeed), HubOriginMlsBasis, and the duplicates and provenance extensions (the hub's own diagnostics). The feed identity is no longer repeated on photos. |
| 2026-10-10 | Changed: $orderby=HubModificationTimestamp on Media or Lookup is refused with 400; an unexpected failure answers an OData error object (InternalError, §8). New: OData responses are gzip-compressed on request (Accept-Encoding: gzip). |
| 2026-10-10 | New: the OpenAPI description and Swagger UI, and complete clients in Python, PHP and JavaScript (§4.9). New clients are granted every feed by default (§2.2). |
| 2026-10-10 | First release of the service: Property, Member, Office, OpenHouse, Media, Lookup; replication by HubModificationTimestamp; extensions source, origin_mls, duplicates, provenance, synthetic, extra_fields. |