Comment on page
RESO Enums To Lookups Transition
This document explains the differences you will need to handle between how we used to feed out our data to how we will feed out the data once this change goes live.
On March 8, 2022 at 8pm MT, we will have an hour maintenance window during which we will release the following changes to our production data and metadata. Once the system comes back up the following changes will be live on all new records returned from the system.
NOTE: We will not backfill older records immediately and it will take time to do that. If for some reason you need to pull older data after the release, your system will need to be able to handle receiving the data both ways.
It is not necessary to re-pull old data for this release. For older data, you should continue to use the values you have in your local data. If they change you will receive an update in the API during normal replication.
The changes that will impact the broadest set of consumers:
- Changing Multiple value strings to Arrays in the output.
- Renaming the expanded Rooms and UnitTypes in the data and in the expand requests.
- Searching by StandardStatus & PropertyType no longer requires Enums prefix notation.
The other changes pertain mostly to metadata and will only be relevant if your system has need to consume and stay up to date with that information:
- New Lookup Resource.
- Metadata has different types for fields that were enumerated.
- Metadata no longer contains enumerations. Obtain lookups through the Lookup resource.
All of this code is live today on the demo server. You should be able to use your existing token to query the demo server to test out the new code prior to the release. If your token is not working in demo or you do not yet have a token, please reach out to [email protected] for further assistance.
You can use all the same replication queries you would normally use but keep in mind that the data set on demo is limited and very stale.
Tip 1: You may want to configure the top value to a smaller value (in the demo environment ONLY) in order to simulate the kind of request volume you might process in a live environment where there is significantly more data to process.
Tip 2: When done testing, don't forget to set your top value back to normal before executing against production or else your requests will be very inefficient and could result in poor performance.
Change | Resources | Affects | Description |
---|---|---|---|
ALL | Data | Previously, fields that were multiple value fields were returned in the data as comma separated string lists. These will now be returned in the data as an array of strings. | |
Property | Metadata, Data | We are changing PropertyRooms and PropertyUnitTypes in expand to match the variable names expected by RESO which are Rooms and UnitTypes | |
Lookup | Replication, Metadata, Data | There will be a new resource requiring replication. The resource will contain all of the lookup values for an mls which were previously contained in the enumerations section of the metadata. | |
Search By Value | ALL | Replication | We allow you to search enumerated fields by value now instead of by Enum code. |
ALL | Metadata | The type value in the metadata for fields that were enumerated used to contain a link to the enums section of the metadata but will now be a String with an annotation indicating the name of the Lookup that applies to that field. | |
ALL | Metadata | The enumerations will no longer be enumerated within the metadata returned by the api service. to obtain the lookups for a given field, the lookup resource must be replicated into your local system and accessed through your local copy of the lookup data. |
RESO expects fields defined as type 'String List, Multi' to be returned as an array of strings. We are changing all fields that previously output as a comma separated string of multiple string values to be an array of multiple string values.
OLD example field output:
"Appliances": "Washer Dryer Hookup,Dishwasher,Oven,Refrigerator",
NEW example field output
"Appliances": [
"Washer Dryer Hookup",
"Dishwasher",
"Oven",
"Refrigerator"
],
Not every mls contains all of these fields. If any of these fields is mapped in their metadata, it will change to be an array of strings.
AccessibilityFeatures |
Appliances |
ArchitecturalStyle |
AssociationAmenities |
AssociationFeeIncludes |
Basement |
BodyType |
BuildingFeatures |
BusinessType |
BuyerAgentDesignation |
BuyerFinancing |
CoBuyerAgentDesignation |
CoListAgentDesignation |
CommonWalls |
CommunityFeatures |
ConstructionMaterials |
Cooling |
CurrentFinancing |
CurrentUse |
DevelopmentStatus |
Disclosures |
DocumentsAvailable |
Electric |
ExistingLeaseType |
ExteriorFeatures |
Fencing |
FinancialDataSource |
FireplaceFeatures |
Flooring |
FoundationDetails |
FrontageType |
GreenBuildingVerificationType |
GreenEnergyEfficient |
GreenEnergyGeneration |
GreenIndoorAirQuality |
GreenSustainability |
GreenWaterConservation |
Heating |
HorseAmenities |
HoursDaysOfOperation |
InteriorFeatures |
IrrigationSource |
LaundryFeatures |
Levels |
ListAgentDesignation |
ListingTerms |
LockBoxType |
LotFeatures |
OperatingExpenseIncludes |
OtherEquipment |
OtherStructures |
OwnerPays |
ParkingFeatures |
PatioAndPorchFeatures |
PetsAllowed |
PoolFeatures |
Possession |
PossibleUse |
PowerProductionType |
PropertyCondition |
RentIncludes |
RoadFrontageType |
RoadResponsibility |
RoadSurfaceType |
Roof |
RoomType |
SecurityFeatures |
Sewer |
ShowingContactType |
ShowingRequirements |
Skirt |
SpaFeatures |
SpecialLicenses |
SpecialListingConditions |
StructureType |
SyndicateTo |
TenantPays |
UnitTypeType |
Utilities |
Vegetation |
View |
WaterfrontFeatures |
WaterSource |
WindowFeatures |
Permission |
RoomFeatures |
SyndicateTo |
SyndicateTo |
We initially implemented our expand for Rooms and UnitTypes to be named the same as the name of the RESO collection. However, RESO expects these collections to be named differently within the Property data on expand and to point to those collections in the nav links. This is how the requests and data will change:
OLD Expand Request:
https://api-demo.mlsgrid.com/v2/Property?$expand=PropertyRooms,PropertyUnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
NEW Expand Request:
https://api-demo.mlsgrid.com/v2/Property?$expand=Rooms,UnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
OLD Expanded Data:
"PropertyRooms": [
{
"RoomDimensions": "13X14",
"RoomType": "Bedroom 1",
"RoomFeatures": "Full Bath",
"RoomKey": "RTC1733786Group_1"
},
{
"RoomDimensions": "12X11",
"RoomType": "Bedroom 2",
"RoomKey": "RTC1733786Group_2"
}
],
NEW Expanded Data:
"Rooms": [
{
"RoomDimensions": "13X14",
"RoomType": "Bedroom 1",
"RoomFeatures": "Full Bath",
"RoomKey": "RTC1733786Group_1"
},
{
"RoomDimensions": "12X11",
"RoomType": "Bedroom 2",
"RoomKey": "RTC1733786Group_2"
}
],
OLD Expanded Data:
"PropertyUnitTypes": [
{
"UnitTypeActualRent": 1,
"UnitTypeType": "Unit 1",
"UnitTypeBathsTotal": 1,
"UnitTypeBedsTotal": 2,
"UnitTypeKey": "RTC2405117Group_1"
},
{
"UnitTypeActualRent": 1,
"UnitTypeType": "Unit 2",
"UnitTypeBathsTotal": 1,
"UnitTypeBedsTotal": 2,
"UnitTypeKey": "RTC2405117Group_2"
}
]
NEW Expanded Data:
"UnitTypes": [
{
"UnitTypeActualRent": 1,
"UnitTypeType": "Unit 1",
"UnitTypeBathsTotal": 1,
"UnitTypeBedsTotal": 2,
"UnitTypeKey": "RTC2405117Group_1"
},
{
"UnitTypeActualRent": 1,
"UnitTypeType": "Unit 2",
"UnitTypeBathsTotal": 1,
"UnitTypeBedsTotal": 2,
"UnitTypeKey": "RTC2405117Group_2"
}
]
OLD Metadata Nav Links:
<NavigationProperty Name="PropertyRooms" Type="Collection(com.mlsgrid.metadata.PropertyRooms)" />
<NavigationProperty Name="PropertyUnitTypes" Type="Collection(com.mlsgrid.metadata.PropertyUnitTypes)" />
NEW Metadata Nav Links:
<NavigationProperty Name="Rooms" Type="Collection(org.reso.metadata.PropertyRooms)"/>
<NavigationProperty Name="UnitTypes" Type="Collection(org.reso.metadata.PropertyUnitTypes)"/>
Because enumerations are being replaced by Lookups, we will now allow searching by the Lookup value instead of requiring the old Enums prefix notation. The old way of querying will continue to work but new requests should move to using the new way. This applies to the PropertyType and StandardStatus query filters.
OLD Query by StandardStatus Request:
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq Enums.StandardStatus'ActiveUnderContract' and OriginatingSystemName eq 'actris'
NEW Query by StandardStatus Request:
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq 'Active Under Contract' and OriginatingSystemName eq 'actris'
There will be a new resource requiring replication. The resource will contain all of the lookup values for an mls which were previously contained in the enumerations section of the metadata.
We recommend using the following queries to replicate and keep your Lookup data up to date:
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and MlgCanView eq true
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and ModificationTimestamp gt [GREATEST ModificationTimestamp FROM YOUR DATABASE FOR THIS RESOURCE]
Replicate from this resource the same way you would replicate from any of the resources using the Greatest ModificationTimestamp from the records you've received so far when querying for the latest changes.
Please do not pull from this resource more frequently than once a day as this resource will not likely change more than once a day. Pulling this resource with the same frequency as the rest of the resources may result in interruption of service for inefficient usage practices.
If you receive an update to MlgCanView: false on any of your lookup records, you should remove it from the list of possible values for that LookupName for the OriginatingSystemName on the record.
The following fields will be searchable for the Lookup resource:
Searchable Lookup Field | Description |
This field is a required search field on every request in version 2.0 of the API. This field is the MLS Grid name for the Originating System. | |
ModificationTimestamp | The timestamp that the record was last modified by the MLS Grid. |
LookupName | The name of the Lookup you want to get the records for. |
Whether or not the record is still being used by the OriginatingSystem. | |
LookupKey | The mls prefixed key - primary identifier of the lookup. |
The LookupKey is the primary identifier for this resource. Each record indicates that a lookup exists and is being used or not used by a particular mls depending on the value of the MlgCanView flag. The ModificationTimestamp will update whenever the Lookup record has changed.
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb678f24b9e68b94c1734e')",
"LookupKey": "ACT61bb678f24b9e68b94c1734e",
"LookupName": "AreaUnits",
"LookupValue": "Square Meters",
"ModificationTimestamp": "2021-12-16T16:21:35.529Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Square Meters",
"MlgCanView": true
}
Fields that have been enumerated used to have the enumerations included as part of the metadata returned by the API service. After this change, all enumerations will be returned using the new Lookup resource. The following is an example of both a single and multiple value field before and after the change:
OLD Metadata:
<Property Name="BodyType" Type="Collection(Enums.BodyType)" MaxLength="1024"/>
...
<Property Name="StandardStatus" Type="Enums.StandardStatus" MaxLength="25"/>
...
<EnumType Name="BodyType" UnderlyingType="Edm.Int64">
<Member Name="DoubleWide" Value="1">
<Annotation Term="RESO.OData.Metadata.StandardName" String="Double Wide"/>
</Member>
<Member Name="SingleWide" Value="2">
<Annotation Term="RESO.OData.Metadata.StandardName" String="Single Wide"/>
</Member>
<Member Name="TripleWide" Value="3">
<Annotation Term="RESO.OData.Metadata.StandardName" String="Triple Wide"/>
</Member>
</EnumType>
...
<EnumType Name="StandardStatus" UnderlyingType="Edm.Int64">
<Member Name="Active" Value="1"/>
<Member Name="ActiveUnderContract" Value="2">
<Annotation Term="RESO.OData.Metadata.StandardName" String="Active Under Contract"/>
</Member>
<Member Name="Canceled" Value="3"/>
<Member Name="Closed" Value="4"/>
<Member Name="ComingSoon" Value="5">
<Annotation Term="RESO.OData.Metadata.StandardName" String="Coming Soon"/>
</Member>
<Member Name="Delete" Value="6"/>
<Member Name="Expired" Value="7"/>
<Member Name="Hold" Value="8"/>
<Member Name="Incomplete" Value="9"/>
<Member Name="Pending" Value="10"/>
<Member Name="Withdrawn" Value="11"/>
</EnumType>
NEW Metadata:
<Property Name="BodyType" Type="Collection(Edm.String)">
<Annotation Term="MLS.OData.Metadata.LookupName" String="BodyType"/>
</Property>
...
<Property Name="StandardStatus" Type="Edm.String">
<Annotation Term="MLS.OData.Metadata.LookupName" String="StandardStatus"/>
</Property>
In order to get the enumerations after this release you will have to query for them in the Lookup resource. For most normal usage, you should receive them by performing normal replication and will then retrieve them from your local data store.
However, if you ever have need to query for a Lookup directly for troubleshooting purposes, here is an example of the same two lookups but queried from the Lookup resource individually.
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'BodyType' and OriginatingSystemName eq 'mfrmls'
{
"@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
"value": [
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb678f24b9e68b94c1768e')",
"LookupKey": "MFR61bb678f24b9e68b94c1768e",
"LookupName": "BodyType",
"LookupValue": "Double Wide",
"ModificationTimestamp": "2021-12-16T16:21:35.843Z",
"OriginatingSystemName": "mfrmls",
"StandardLookupValue": "Double Wide",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c178dd')",
"LookupKey": "MFR61bb679024b9e68b94c178dd",
"LookupName": "BodyType",
"LookupValue": "Single Wide",
"ModificationTimestamp": "2021-12-16T16:21:36.083Z",
"OriginatingSystemName": "mfrmls",
"StandardLookupValue": "Single Wide",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c179c3')",
"LookupKey": "MFR61bb679024b9e68b94c179c3",
"LookupName": "BodyType",
"LookupValue": "Triple Wide",
"ModificationTimestamp": "2021-12-16T16:21:36.163Z",
"OriginatingSystemName": "mfrmls",
"StandardLookupValue": "Triple Wide",
"MlgCanView": true
}
]
}
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'StandardStatus' and OriginatingSystemName eq 'actris'
{
"@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
"value": [
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679024b9e68b94c17bf8')",
"LookupKey": "ACT61bb679024b9e68b94c17bf8",
"LookupName": "StandardStatus",
"LookupValue": "Canceled",
"ModificationTimestamp": "2021-12-16T16:21:36.393Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Canceled",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c180c1')",
"LookupKey": "ACT61bb679124b9e68b94c180c1",
"LookupName": "StandardStatus",
"LookupValue": "Expired",
"ModificationTimestamp": "2021-12-16T16:21:37.056Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Expired",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181b8')",
"LookupKey": "ACT61bb679124b9e68b94c181b8",
"LookupName": "StandardStatus",
"LookupValue": "Delete",
"ModificationTimestamp": "2021-12-16T16:21:37.135Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Delete",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181bf')",
"LookupKey": "ACT61bb679124b9e68b94c181bf",
"LookupName": "StandardStatus",
"LookupValue": "Withdrawn",
"ModificationTimestamp": "2021-12-16T16:21:37.135Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Withdrawn",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c18331')",
"LookupKey": "ACT61bb679124b9e68b94c18331",
"LookupName": "StandardStatus",
"LookupValue": "Pending",
"ModificationTimestamp": "2021-12-16T16:21:37.286Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Pending",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c1869e')",
"LookupKey": "ACT61bb679124b9e68b94c1869e",
"LookupName": "StandardStatus",
"LookupValue": "Incomplete",
"ModificationTimestamp": "2021-12-16T16:21:37.588Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Incomplete",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c187ef')",
"LookupKey": "ACT61bb679124b9e68b94c187ef",
"LookupName": "StandardStatus",
"LookupValue": "Active",
"ModificationTimestamp": "2021-12-16T16:21:37.738Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Active",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c18a63')",
"LookupKey": "ACT61bb679124b9e68b94c18a63",
"LookupName": "StandardStatus",
"LookupValue": "Coming Soon",
"ModificationTimestamp": "2021-12-16T16:21:37.965Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Coming Soon",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679224b9e68b94c18c1d')",
"LookupKey": "ACT61bb679224b9e68b94c18c1d",
"LookupName": "StandardStatus",
"LookupValue": "Active Under Contract",
"ModificationTimestamp": "2021-12-16T16:21:38.122Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Active Under Contract",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679924b9e68b94c1c8c1')",
"LookupKey": "ACT61bb679924b9e68b94c1c8c1",
"LookupName": "StandardStatus",
"LookupValue": "Hold",
"ModificationTimestamp": "2021-12-16T16:21:45.259Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Hold",
"MlgCanView": true
},
{
"@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679924b9e68b94c1ca2d')",
"LookupKey": "ACT61bb679924b9e68b94c1ca2d",
"LookupName": "StandardStatus",
"LookupValue": "Closed",
"ModificationTimestamp": "2021-12-16T16:21:45.412Z",
"OriginatingSystemName": "actris",
"StandardLookupValue": "Closed",
"MlgCanView": true
}
]
}
Last modified 1yr ago