MLS Aligned API Learning Center

Read the latest documentation on the MLS Aligned API.

MLS Aligned is a collaboration of forward thinking organizations with a goal to create open-source solutions that better MLS.
...
The API is a brand new way for an MLS to share data without replication!
Responsive image
It's the first effort from this newly formed collaboration and we believe it's a glimpse into the power of a dedicated group effort without the hindrance of over-restrictive governance.
A replicated data distribution system is a highly-complex, architectured adventure. One that involves a “source” from which scripts copy information to a satellite hub on a schedule (normally every 15 minutes). The satellite hub becomes the “new source”.
Follow up scripts run daily/weekly/monthly in order to clean up bad data OR catch missed information.
Responsive image
This is the tried-and-true method of an MLS data share and while other industries do not sync data in this manner - our industry has become quite good at it. That said, even the best replicated systems are NOT immune to issues. Orphaned data and misplaced information will happen.

The end result becomes thousands of websites displaying listing information through channels of varying quality.
It’s really simple... Bad data leads to customer fails and customer fails affect us all.
MLS Aligned presents a new way to conduct an MLS data share without any sharing. The data NEVER leaves the MLS.

The MLS is fully vested in the integrity of the information provided so the data is kept with its best asset - the MLS!
The API interprets RESO/OData WEB API queries and returns data directly from the host MLS.
No replicated MLS data share needs to be invested in - we leverage the existing MLS repository!

Code named the man-in-the-middle.
Responsive image
The MLS Aligned API is designed to work with any type of RESO MLS repository - out of the box and in real-time.
It will handle the translation of fields to provide the same payload regardless of the source.
In a real-world scenario, a client would call the MLS Aligned API just like any other RESO/WEB API but would benefit from the following advantages:
  • Data delivered in real-time from ALL host MLS repositories
  • One (1) RESO/OData end point for ALL MLS participants
  • One (1) RESO/OData authentication method for ALL MLS data
  • One (1) RESO compliant IDX payload from ALL MLS participants
Further info on the RESO/OData WEB API can be found here
The MLS Aligned API is a cloud-based manager that brokers data from existing MLS repositories into a single unified RESO payload - in real-time.

It uses server-side memory mapping techniques and modern cloud-based microservices to enhance performance of reading LIVE MLS repositories.

A simple admin tool is used by the MLS to setup the logic behind identifying the fields needed for the unified payload.

Developers send RESO/OData queries and the MLS Aligned API handles the rest. This includes authentication and delivery of the data needed.
The concept is similar to how PayPal works.

PayPal doesn't replicate everyone's bank account with 15 minute updates OR conducts transactions on replicated data.
PayPal links your existing bank account repository and uses it during live transactions with your authorization.

The bank is fully vested into the accuracy of your account. The data is kept with its best asset - THE BANK.
Certification on the RESO Data Dictionary has made great progress for the standard. It really makes life easier for development on a grand scale. That said, it's NOT plug-n-play. Even datasets that are Platinum Certified will have subtle differences in the payload/export resulting in customization from the software development community.

Localized real estate data is not a bad thing - it’s actually a good thing. Our uniqueness defines our value.
From a software development standpoint, however, it can become a hurdle to overcome.

The MLS Aligned API tackles this issue with a unified payload - regardless of the source. The MLS controls what fields on their side equates to the payload provided by the MLS Aligned API (currently the RESO defined IDX payload).
Further info on the RESO IDX payload can be found here
Like most API’s, key information is passed inside request headers. This allows for server-to-server communications.
The MLS ALigned API requires the RESO OUID of the host MLS desired in each request header.
The RESO OUID is a unique identifier of all participating real estate organizations.
Further information on the RESO OUID is available here
The MLS Aligned group set out to test performance with a series of technical demonstrations that focused in the following areas:
  • Applications that are dependant on API access in real-time
  • Replication via API
  • Demonstration of performance
The tech demonstrations have proven to show NO LAG in our proof-of-concept (POC) testing labs.
Note: performance issues on the host MLS repository will affect the MLS Aligned API.
Future roadmap R&D will look at tackling this issue.
View the LIVE status of all participating MLS host repositories here
Since the MLS Aligned API brokers data from different host MLSs - the metadata document will technically be different for each.

Don't be discouraged though - there are many common use cases for RESO/OData queries that will run on ALL MLS repositories out of the box. Customization is really only needed when searching by enumeration OR a field that is not common with each MLS.

The MLS Aligned API will customize the returning payload from ALL MLS repositories into the exact same data dictionary fields... A unified payload.
Metadata for enumerated fields will still need to be managed by the client (future roadmap R&D will look at tackling this issue).
Developers can pull the metadata document just like they do today - via RESO/OData WEB API documentation:
  • http://aligned.metromls.com/RESO/OData/$metadata
The MLS Aligned API will display the same live metadata document that is being sent from the host MLS.
You will typically want an Accept header of application/json for use of the MLS Aligned API but accessing the RESO metadata document will require application/XML instead
The depth of OData support is limited to the the host MLS repository you are working with.

Most basic OData functions including $select, $filter, $orderby, $top and $count will work with all host MLS.
The MLS Aligned API can be used in the following use cases:

  • Applications that are dependant on API access in real-time
  • Replication via API
  • Data Validation
  • Metadata document discovery
Short answer YES!


The MLS Aligned API demonstrates respect to the RESO documented standards throughout.
The API is built from the ground up with RESO standards in mind.
  • RESO/OData API defined URI endpoint naming convention
  • RESO/OData API searches
  • RESO IDX defined payload
  • RESO WEB API defined authentication
  • RESO OUID integrated with authentication
  • RESO Internet Tracking solution within
The MLS needs a live API repository. That’s it.

The MLS would be given a login to manage the MLS Aligned API with their content using a simple admin tool.
Setup is a one-time event - updates/changes can be performed at anytime.
Step 1: Endpoint URL
The MLS Aligned API endpoint URI is http://aligned.metromls.com/RESO/OData/.

We support the RESO/OData defined URI naming convention where RESO Data Dictionary resources are added to the end of the endpoint URI (i.e. http://aligned.metromls.com/RESO/OData/Property OR http://aligned.metromls.com/RESO/OData/Media).
Step 2: Authentication
The MLS Aligned API uses a non-expiring OAuth2 Bearer access token.
NOTE - never provide your access token to a web browser or other end user agent.

Best practice is to keep on the server-side only accessible by your applications. For further help/info contact clambrou@metromls.com.
To request data from the MLS Aligned API, you will need to provide four (4) headers.
The Authorization header, the Accept header, the OUID header and a custom MLS-Aligned-User-Agent header.

For the Authorization header you will use Bearer <your_access_token>.

You will typically want an Accept header of application/json but, if you are accessing the metadata document of the RESO metadata you will need to use application/xml.

The OUID header will identify the MLS data you are attempting to work with.
Multiple OUIDs need to be pipe ( | ) delimited.
Currrent Live OUIDs
  • Metro MLS - M00000662
  • ARMLS - M00000048
  • Utah Real Estate - M00000628
  • RMLS - M00000531
  • MLS Listings - M00000101
The MLS Aligned API endpoint requires a MLS-Aligned-User-Agent header, so you must also provide that when accessing the API. You would pass the name of your application in this header.

Example Headers
{
MLS-Aligned-User-Agent: <your application name>,
Authorization: Bearer <your access key>,
OUID: <the RESO OUID of the MLS>,
Accept: application/json
}

Step 3: The Search
The following RESO OData searches (aka filter, aka queries) will work with all host MLS APIs

Listings Last Modified on 2018-08-02
http://aligned.metromls.com/RESO/OData/Property/?$filter=year(ModificationTimestamp) eq 2018 and month(ModificationTimestamp) eq 8 and day(ModificationTimestamp) eq 2&$top=20&$count=true
Pull Media Data with ListingKey
http://aligned.metromls.com/RESO/OData/Property('[ListingKey]')/Media/
Listings Last Modified on 2018-08-10 in the hour of 5AM
http://aligned.metromls.com/RESO/OData/Property/?$filter=year(ModificationTimestamp) eq 2018 and month(ModificationTimestamp) eq 8 and day(ModificationTimestamp) eq 2 and hour(ModificationTimestamp) eq 5

Step 4: Sample Payload
The MLS Aligned API response will be a JSON formatted payload.

The payload will always contain the MLS Aligned fixed RESO defined IDX payload fields - no matter which MLS host API is accessed.
The payload will include certain OData necessities like odata.count and odata.nextLink to allow for pagination.
Sample Payload
{
"@odata.context": "http://aligned.metromls.com/RESO/OData/$metadata#Property",
"@odata.nextLink": "http://aligned.metromls.com/RESO/OData/$count=true&$filter=year(ModificationTimestamp) eq 2018 and month(ModificationTimestamp) eq 8 and day(ModificationTimestamp) eq 2&$skip=8&$top=5",
"@odata.count": 282,
"value": [
{
"Appliances ": "Refrigerator, Stove, Beer Cooler",
"ArchitecturalStyle": "Bungalow",
"AssociationAmenities": "",
"AssociationFee": "100",
"AssociationYN": "Y",
"AttachedGarageYN": "Y",
"Basement": "",
"BathroomsFull": "4",
"BathroomsHalf": "",
"BathroomsTotalInteger": "3",
"BedroomsTotal": "4",
"City": "RunningSprings",
"CoListAgentFirstName": "George",
"CoListAgentFullName": "George A Sandberg",
"ListOfficeName": "Vandelay Industries"
...
View a sample of the MLS Aligned API payload here
Step 4: Error Messages
API Error Results

{ "staus" : "error" , "msg" : "Invalid Authentication Headers" }
One of the three (3) mandatory headers are missing

{ "status" : "error" , "msg" : "Invalid OUID Header" }
The OUID found in the header was either missing OR invalid

{ "status" : "error" , "msg" : "Invalid Token" }
The access token used was invalid

{ "status" : "error" , "msg" : "Invalid/Bad OData Call" }
The OData query was either not valid OR not part of the host MLS API supported library

{ "status" : "error" , "msg" : "Call Exceeds Max Allowed $top of 25" }
Currently, the MLS Aligned API has a restriction of 25 items per call

{ "status" : "error" , "msg" : "System Error" }
Something is wrong with the man-in-the-middle operations :(
Step 5: Metadata
Metadata from each MLS will be needed for managing Enumerations. We hope to tackle this issue in 2019.

To query the MLS Aligned API BOT for the MLS Metadata - use the traditional OData $metadata call
http://aligned.metromls.com/RESO/OData/$metadata
Note the MLS metadata you request is determined by the OUID header

Note remember that RESO/OData metadata calls are always returned as XML payloads