Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

Getting Started

To get started using the MLS Router API, please sign up on RF Dashboard. (How to Sign Up on RF Dashboard)

When we set up your account, we'll provide a Client ID, Client Secret, and an API key that you'll need for use in API requests.

Authentication

To access the MLS Router API, authentication is required. The API uses the OAuth2 Client Credentials flow for authentication.

Obtaining Access Token

To authenticate, send a POST request to the following endpoint:

POST https://realtyfeed-sso.auth.us-east-1.amazoncognito.com/oauth2/token

The request should include the following in the Request Body:

Parameter

Description

client_id

The client ID provided by Realtyna

client_secret

The client secret provided by Realtyna

grant_type

The grant type, which should be "client_credentials"

And also include the following in the Request Headers:

Parameter

Description

Content-Type

application/x-www-form-urlencoded

Accept-Encoding

gzip, deflate, br

Accept

*/*

If the authentication request is successful, you will receive a JSON response with the following values:

{
  "access_token": "<access_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
  • access_token: This is the authorization token that needs to be passed in the Authorization header of API requests.

  • expires_in: The duration of validity for the token in seconds (currently set to 3600).

  • token_type: The type of token being returned (currently set to "Bearer").

Need more help? See How to get Authentication code

Reading the Metadata

Once you've authenticated, the next step for building a client is finding out what data you can get out of MLS Router API. To do this, you query the metadata endpoint.

GET https://api.realtyfeed.com/reso/odata/$metadata

Now that we know what fields are available via MLS Router API, it's time to start fetching property data.

Retrieving Data

To retrieve data from the MLS Router API, please include the following headers in each request:

  • Authorization: Set this header with the value "Bearer <access_token>" (replace <access_token> with the actual access token obtained during authentication).

  • x-api-key: Include this header with the API key provided by Realtyna.

  • Origin: Include this header with the API key provided by Realtyna. (Optional)

  • Referer: Include this header with the API key provided by Realtyna. (Optional)

The endpoint structure of all search requests is:

GET https://api.realtyfeed.com/reso/odata/{resource}

Valid resource values include the names of the valid RESO resources: Property, Member, Office and OpenHouse.

RESO Media is nested within the Property Resource.

By default, MLS Router API returns 10 records per query. If this is your first foray into MLS Router API, it will be enough for you to learn about the structure of the data that's returned.

Parameter

Description

@odata.nextLink

URI for getting the next set of records. Will only be present when there are more records to retrieve.

value

An array of objects. The data you came for.

While you look through the data you have pulled back, there is one field that you should pay special attention to: ListingKey. This field is the unique identifier for the Property record.

ListingKey is the unique identifier for Property records

Request Parameters

The MLS Router API supports the following parameters for search requests:

Parameter

Description

$top

To get more records per query, we use the $top parameter. If you want just one record, you can specify $top=1, or if you want one hundred, $top=100. (default is 10 - max value is 200)

$skip

Use $skip to skip over a number of records. This is most useful in combination with $top to iterate over the results of a query. (default is 0)

$select

You can limit the fields you want with $select. For example, if you want just the ListingKey and the StandardStatus, you would use $select=ListingKey, StandardStatus. If you want all the fields, you would use $select=ALL

$filter

You can get specific records you want with the $filter.

$orderby

You can sort results via the $orderby parameter. This parameter accepts “ASC” and “DESC” as an argument (default is “ASC”).

The supported parameters can be combined as needed

$filter

The $filter system query option restricts the set of items returned. MLS Router supports a set of built-in filter operations, as described in this section:

Operator

Meaning

Example

eq

Equal To

ListingKey eq '123456'

ne

Not Equal To

PropertyType ne 'Residential'

gt

Greater Than

BedroomsTotal gt 3

ge

Greater Than or Equal To

BathroomsTotalInteger ge 2

lt

Less Than

ListPrice lt 350000

le

Less Than or Equal To

LotSizeArea le 5

and

Both conditions are true

BedroomsTotal eq 3 and BathroomsTotalInteger eq 2

or

Either condition is true

BedroomsTotal ge 3 or BathroomsTotalInteger ge 3

in

Value is in List

StandardStatus in ('Active', 'Pending')

These operators can be combined to form very complex queries, e.g. ((ListPrice lt 300000 and LotSizeAcres lt 3) or (BedroomsTotal gt 4 and StandardStatus eq 'Active'))

Working with strings in $filter:

Strings are relatively straightforward in MLS Router API. They are always enclosed in single quotes (') and if you need a single quote in the string, you simply double it up, e.g. 'O''Brien'.

In addition to all of the basic operators that you can use with strings, there is a function to help out as well:

Function

Description

contains(haystack, 'needle')

Returns true if needle is found in haystack

Working with geo coordinates in $filter:

Function

Description

geo.distance(Coordinates, POINT(-96.818747 32.928812)) lt 10km

Returns property listings within geo distance of 10km from a specific point

Retrieving Single Record

Use this endpoint to get details about a specific record:

GET https://api.realtyfeed.com/reso/odata/{resource}('resource_id')

The API returns record within the specified resource having a primary key value matching the provided resource_id. For example:

Request

GET https://api.realtyfeed.com/reso/odata/Property('ListingKey')
or
GET https://api.realtyfeed.com/reso/odata/Member('MemberKey')

Don’t hesitate to contact Realtyna Support, if you have any questions.

Errors

401 Unauthorized

A 401 http response results when authentication fails. This is likely due to using an invalid x-api-key or account suspension.

403 Forbidden

A 403 http response results when an authenticated user does not have adequate permissions to perform the requested operation or access the specified resource.

400 Bad Request

A 400 http response results when a request is poorly formatted or does not meet validation for the specified operation.

400 responses contain an array of messages that a developer may parse to determine the parameter and reason for why the request failed.

406 Not Accepted

A 406 http response results when a request is not satisfied due to rule or policy being broken.

500 Internal Server Error

A 500 http response results when an unexpected problem occurs with a request. If after several retries the 500 error still persists, it should be escalated to the Realtyna Support Team for troubleshooting.

Searchable Fields:

  • Property

Field

Description

ListingKey

ModificationTimestamp

ListingId

PropertyType

A list of types of properties such as Residential, Lease, Income, Land, Mobile, Commercial Sale, etc...

PropertySubType

A list of sub types to Residential, Residential Lease, Manufactured in Park, Commercial and Business Opportunity listings. e.g. Single Family Residence, Condominium, Manufactured on Land, Townhouse, Multi Family, Office, Retail, etc.

ListPrice

The current price of the property as determined by the seller and the seller's broker. For auctions this is the minimum or reserve price.

BathroomsTotalInteger

The simple sum of the number of bathrooms. For example for a property with two Full Bathrooms and one Half Bathroom, the Bathrooms Total Integer will be 3.

BedroomsTotal

The total number of bedrooms in the dwelling.

StandardStatus

The status of the listing as it reflects the state of the contract between the listing agent and seller or an agreement with a buyer (Active, Active Under Contract, Canceled, Closed, Expired, Pending, Withdrawn).

LotSizeArea

The total area of the lot.

LivingArea

The total livable area within the structure.

BuildingAreaTotal

Total area of the structure. Includes both finished and unfinished areas.

OriginatingSystemName

The name of the Originating record provider. Most commonly the name of the MLS.

City

The city in listing address.

PostalCode

The postal code portion of a street or mailing address.

UnparsedAddress

The UnparsedAddress is a text representation of the address with the full civic location as a single entity. It may optionally include any of City, StateOrProvince, PostalCode and Country.

YearBuilt

The year that an occupancy permit is first granted for the house or other local measure of initial habitability of the build.

ListAgentFullName

The full name of the listing agent. (First Middle Last)

ListOfficeName

The legal name of the brokerage representing the seller.

StoriesTotal

The total number of floors in the building.

TaxLot

A type of legal description for land in developed areas where streets or other rights-of-ways delineate large parcels of land referred to as divided into lots on which homes or other types of developments are built.

TaxBlock

A type of legal description for land in developed areas where streets or other rights-of-ways delineate large parcels of land referred to as divided into lots on which homes or other types of developments are built.

GarageSpaces

The number of spaces in the garage(s).

Cooling

A list describing the cooling or air conditioning features of the property.

InteriorFeatures

A list of features or description of the interior of the property included in the sale/lease.

ExteriorFeatures

A list of features or description of the exterior of the property included in the sale/lease.

PublicRemarks

Text remarks that may be displayed to the public.

LaundryFeatures

A list of features and locations where the laundry is located in the property being sold. i.e. Gas Dryer Hookup, In Kitchen, In Garage, etc.

FireplacesTotal

The total number of fireplaces included in the property.

PoolFeatures

A list of features or description of the pool included in the sale/lease.

PetsAllowed

Are pets allowed at the property? A list of yes, no and more detailed restrictions/allowances.

WaterfrontFeatures

Features of the waterfront on which the property is located.

AccessibilityFeatures

A list or description of the accessibility features included in the sale/lease.

LotFeatures

A list of features or description of the lot included in the sale/lease.

  • Member

Field

Description

MemberFullName

MemberEmail

MemberMlsId

MLS ID of the agent in MLS

OfficeMlsId

MLS ID of the agent’s Office in MLS

ModificationTimestamp

OriginatingSystemName

MemberKey

Agent’s system Key in MLS

MemberStatus

OfficeKey

MemberDirectPhone

  • Office

Field

Description

OfficeName

OfficeEmail

OfficeMlsId

MLS ID of the agent in MLS

ModificationTimestamp

OriginatingSystemName

OfficeStatus

OfficeKey

  • OpenHouse

Field

Description

OpenHouseKey

ListingKey

Get Openhouse records based on associated ListingKey

ListingId

Get Openhouse records based on associated ListingID

ModificationTimestamp

OriginatingSystemName

OpenHouseStatus

OpenHouseDate

  • No labels