Rapattoni Developer Resources

RESO Web API

Rapattoni offers an implementation of RESO's Web API, and provides data using the RESO Data Dictionary.

Authentication

Authentication URL:

  • https://retsidentityapi.raprets.com/mls/oauth/token

When accessing the Authentication URL, you will need to pass the following in the body of a POST request:

  • grant_type: Currently we only support a grant type of “password”.
  • client_id: given to you by the MLS.
  • client_secret: a password associated with the client id, it is a randomly generated has. If this is ever compromised a new one may be generated by MLS staff.
  • Username: The MLS ID created in membership.
  • Password: The password associated with the above MLS ID.

Please note, standard web browsers cannot pass all of the criteria; an API client program should be used. One simple testing client is Postman, available here: Get Postman

The body of the request should look similar to the following example:

  • grant_type=password&client_id=ClientID&client_secret=Secret&username=Username&password=Password

You will also need to include the header:Content-Type: application/x-www-form-urlencoded

If the transaction is successful, then the response body will be a JSON object containing the access token, token type, seconds till expiration, refresh token, username, date time issued and date time of expiration. The token type will always be “bearer”:
{
“access_token”: “80957f49b90d449c99dfb01871676e3e”,
“token_type”: “bearer”,
“expires_in”: 604799,
“refresh_token”: “018c9daf657c4fd0bccf1268f77b063c”,
“userName”: “username”,
“.issued”: “Fri, 17 Mar 2017 16:41:32 GMT”
“.expires”: “Fri, 24 Mar 2017 16:41:32 GMT”
}

API Transactions

All transactions must include the Authorization header with the value being the client’s current bearer token obtained from the transaction with our Authentication server.

Here is an example of the how the Authorization header with the bearer token should appear in the HTTP request:

  • Authorization:bearer 80957f49b90d449c99dfb01871676e3e

Responses, unless otherwise specified, will be in the JSON format.

The Service Document is available via a get request against the root URL (http://retsapi.raprets.com/mls/RESO/odata). By default, this will return in the XML format but can be requested in JSON by passing “application/json” in the Accept header. This document is a standard OData resource listing all top-level entity sets exposed by the service.( ODatav4 10.1)

The Metadata Document is available via a get request against the root URL with /$metadata appended (i.e. http://retsapi.raprets.com/mls/RESO/odata/$metadata). This resource describes the API’s data model; including data types, relationships between entity sets, and available fields (ODatav4 11.1.2). This resource is only available in the XML format.

The DataSystem endpoint will list all available Resources. The Classes associated with each endpoint can be seen by using the $expand query option as follows:
http://retsapi.raprets.com/mls/RESO/odata/DataSystem?$expand=Resources
Example DataSystem Results:

                    
{
    "@odata.context": "http://retsapi.raprets.com/mls/RESO/OData/$metadata#DataSystem/$entity",
    "Id": 1,
    "Mls": "mls",
    "Name": "Rapattoni Rets",
    "ServiceUri": "http://retsapi.raprets.com/mls/RESO/OData",
    "DateTimeStamp": "2017-03-16T10:18:19.26-07:00",
    "TransportVersion": "1.0.2",
    "DataDictionaryVersion": "1.6",
    "Resources": [
        {
            "Id": 1,
            "DataSystemId": 1,
            "Name": "Property",
            "ResourcePath": "/Property",
            "Description": "The property endpoint",
            "DateTimeStamp": "2016-07-11T14:20:13.863-07:00",
            "TimeZoneOffset": 0,
            "Localization": [
                {
                    "Name": "Land",
                    "ResourcePath": "/Property?Class=Land",
                    "Description": "Contains data for Land searches.",
                    "DateTimeStamp": "2017-11-07T18:16:43.1-08:00"
                },
                {
                    "Name": "Residential",
                    "ResourcePath": "/Property?Class=Residential",
                    "Description": "Contains data for Residential searches.",
                    "DateTimeStamp": "2017-11-07T18:16:43.1-08:00"
                }
            ]
        },
        {
            "Id": 2,
            "DataSystemId": 1,
            "Name": "Agent",
            "ResourcePath": "/Agents",
            "Description": "The agent endpoint",
            "DateTimeStamp": "2016-07-11T14:20:13.863-07:00",
            "TimeZoneOffset": 0,
            "Localization": [
                {
                    "Name": "Member",
                    "ResourcePath": "/Agents?Class=Member",
                    "Description": "Contains data for Agent searches.",
                    "DateTimeStamp": "2017-07-18T23:12:38.953-07:00"
                }
            ]
        }
    ]
}
                            
                      

Entity Set Queries:Entity Set queries use the default OData format; the root URL is appended with “/EntitySet”. The ResourcePath elements returned from the DataSystem query are the exact entity set values to use. Queries against any entity set MUST include the Class query argument; the Classes available for each entity set are available via the DataSystem endpoint in the Localization arrary (see above DataSystem example). The following URL would be used for querying the Property entity set and the Residential Class:

  • http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential

When Querying against Entity Sets, our implementation of the RESO Web API supports most OData 4 query options, functions and operators. The below list are those query options and some of their associated supported functions and operators. Please see the OData 4 specification for further information in regards to these:

  • $select : This is used to specify what fields you would like to have return in the results.(ODatav4 11.2.4.2)
    • Example URL: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$select=ListingKeyNumeric,ListingId,StandardStatus,City
  • $filter : restrict the returned entities to only those matching the filter criteria (ODatav4 11.2.5.1)
    • Operators
      • eq : Equals
        • Example : StandardStatus equals Active: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=StandardStatus eq 'Active'
      • ne : Not Equals
        • Example : City not equals Granite Bay: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=City ne 'Granite Bay'
      • gt : Greater than
        • Example: BathroomsTotalInteger greater than 2: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger gt '2'
      • lt : Less than
        • Example: BathroomsTotalInteger less than 2: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger lt '2'
      • and: Logical and
        • Example: BathroomsTotalInteger less than 2 and City equals San Francisco: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger lt '2' and City eq 'San Francisco'
      • or: Logical or
        • Example: BathroomsTotalInteger less than 2 or City equals San Francisco: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger lt '2' or City eq 'San Francisco'
      • not: Logical negation, used in conjunction with other functions and operators to create a negative comparison.
        • Example: BathroomsTotalInteger less than 2 and not City equals San Francisco: http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger lt '2' and not City eq 'San Francisco'
      • (): Functions and operators can be nested using parentheses for precedence.
        • Example: BathroomsTotalInteger less than 2 or (City equals San Francisco and MlsStatus equals Sold): http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=BathroomsTotalInteger lt '2' or (City eq 'San Francisco' and MlsStatus eq 'Sold')
      • has: The has operator returns true if the right hand operand is an enumeration value whose flag(s) are set on the left operand. The null value is treated as unknown, so if one operand evaluates to null, the has operator returns null. Please refer to the metadata for supported Enumeration values.
        • Example: The value, or one of the values,in ListingTerms is 'Cash': http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$filter=ListingTerms has Rapattoni.Rets.Api.Models.ListingTerms'Cash'
    • Functions
      • contains: string contains, syntax is: contains(FieldName,’string’)
      • endswith: string ends with, syntax is: endswith(FieldName,’string’)
      • startswith: string starts with, syntax is: startswith(FieldName,’string’)
      • day: return the day component from a DateTimeOffset or Date
      • hour: return the hour component from a DateTimeOffset
      • minute: return the minute component from a DateTimeOffset
      • second: return the second component from a DateTimeOffset
      • month: return the month component from a DateTimeOffset or Date
      • year: return the year component from a DateTimeOffset or Date
    • Complex Filter Example:
      • Property?Class=Residential$filter=(contains(PublicRemarks,‘pool’) and City eq ‘Ventura’) or ListingTerms has Rapattoni.Rets.Api.Models.ListingTerms'Cash'
  • $top : Limit the number of results returned.(ODatav4 11.2.5.3)
    • Example: Returning the first 10 records http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$top=10
  • $skip : skip a number of records before returning results(ODatav4 11.2.5.4)
    • Example: Skip the first 100 records, then return results. http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$skip=100
  • $orderby: order the results by a specific field’s value; use asc or desc to specify ascending or descending. To order by multiple criteria use comma delimiting(ODatav4 11.2.5.2)
    Examples:
    • http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$orderby=City desc http://retsapi.raprets.com/mls/RESO/OData/Property?Class=Residential&$orderby=Status asc
  • &: Multiple query options can be included at once, each separated by an “&”
    • Example: Property?Class=Residential&$filter=MlsStatus eq 'Active'&$select=ListingKeyNumeric,City&$top=10

  • Single Entity: To return one specific Entity, the format is EntitySet(key); note the Class parameter must still be included. For example, if pulling back Residential listing 101 from the Property entity set, the root URL would be appended with /Property(101). Please refer to the metadata to find the primary key for each Entity Set.
    • Example: https://api.rapmagic.com/cust/odata/Property(101)?Class=Residential