RESO Web API Overview
Built within the Spark® API is a /Reso/OData endpoint that implements the
RESO Web API
and provides data using the
RESO Data Dictionary.
The documentation we provide does not fully document the RESO Web API itself; rather, it's meant to get you up and running on our implementation of the standard.
1. Overview
The RESO Web API version 3 endpoint is at:
https://replication.sparkapi.com/Version/3/Reso/OData/Version 3 is now our recommended version, especially for new developers who are not already using RESO Web API version 2. All documentation examples use version 3 and assume a replication role. For version 2, use either of the following endpoints:
https://replication.sparkapi.com/Reso/OData/
https://replication.sparkapi.com/Version/2/Reso/OData/
Because our RESO Web API shares the same authentication and authorization infrastructure as the Spark API, you can use the same API keys provided for the Spark API to access the RESO Web API endpoints.
2. Authorization
The method for obtaining authorization from end users and making authenticated requests is identical to accessing the Spark API directly. See our authentication documentation for more information.
3. Making Requests
Resources
Our RESO Web API provides the following distinct endpoints:
Retrieving Metadata
Metadata is accessible at:
https://replication.sparkapi.com/Version/3/Reso/OData/$metadataWhen fields have enumerated lists of values, possible values are advertised in the Lookup resource:
https://replication.sparkapi.com/Version/3/Reso/OData/LookupRetrieving Data
Using the Property resource as our example, all properties can be retrieved at:
https://replication.sparkapi.com/Version/3/Reso/OData/PropertyAn individual property can be retrieved at:
https://replication.sparkapi.com/Version/3/Reso/OData/Property('<ListingKey>')
For example, if a listing's ListingKey is 20100000000000000000000000, your request should be:
https://replication.sparkapi.com/Version/3/Reso/OData/Property('20100000000000000000000000')
To access Property Media, Rooms and other related resource records, FBS recommends utilizing the $expand parameter. All allowed expansions are listed in the NavigationProperty entities in your feed metadata (see above).
https://replication.sparkapi.com/Version/3/Reso/OData/Property?$expand=Media,OpenHouse
If desired, these related resource records can instead be accessed as a subresource of each Property record. Here are a couple examples:
https://replication.sparkapi.com/Version/3/Reso/OData/Property('20100000000000000000000000')/Mediahttps://replication.sparkapi.com/Version/3/Reso/OData/Property('20100000000000000000000000')/OpenHouse
Request Parameters
Each service supports some or all of the request parameters documented on our RESO request parameters page.
Response Description
This OData service only responds to JSON format except for the $metadata endpoint, which returns XML.
Encoded values
OData specifications that the RESO Web API is built upon dictate that certain data attributes and values can't contain spaces, non-alpha-numeric characters, etc. When they do, the values need to be encoded. For this reason some custom field names are encoded, and the corresponding human-readable names can be looked up in the metadata. The EntityType Name="CustomFields" section of the metadata will list all custom field names and their human readable translations. Here's an example of a metadata entry that connects an encoded name and a display name:
<Property Name="Documents_co_Exclusive_sp_Right_sp_to_sp_Sell_sp__lbracket_private_rbracket_" Type="Edm.Boolean">
<Annotation Term="MLS.OData.Metadata.LocalName" String="Documents Exclusive Right to Sell [private]"/>
</Property>