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