openapi: 3.0.0
info:
title: SimplyRETS API
version: 1.0.0
description: >
The SimplyRETS API is an exciting step towards making it easier
for software developers and real estate professionals to work
together and _build something awesome_ with real estate data!
The docs below describe all of the endpoints, search parameters,
and responses from SimplyRETS. You can **make live API requests on
this page** by clicking the "Authorize" button below and enter
your API keys (or `simplyrets`/`simplyrets` for the demo data).
[Contact us](https://simplyrets.com/#home-contact) if you have any
question, comments, or feedback.
**Additional resources**
- [Accessing live MLS data](https://simplyrets.com/blog/getting-set-up.html)
- [Create an app](https://simplyrets.com/account#/apps/new)
- [Features for IDX compliance](/topics/fields-and-features-for-idx-compliance)
- [API examples and help topics](/#topics)
- [Plans & pricing](https://simplyrets.com/#home-pricing)
tags:
- name: Listings
- name: OpenHouses
- name: Agents
- name: Analytics
- name: Metadata
paths:
/openhouses:
get:
summary: The SimplyRETS open houses API
tags:
- OpenHouses
responses:
'200':
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/OpenHouse'
type: array
application/vnd.simplyrets-v0.1+json:
schema:
items:
$ref: '#/components/schemas/OpenHouse'
type: array
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- required: false
in: query
name: type
description: |
Request open houses by it's listing's property type. This defaults to
Residential, and you can only specify one type in a single query.
schema:
type: string
enum:
- residential
- rental
- mobilehome
- condominium
- multifamily
- commercial
- commerciallease
- land
- farm
- required: false
in: query
name: listingId
description: |
Request open houses for a specific `listingId`.
schema:
type: string
- required: false
in: query
name: cities
description: >
Filter the open houses returned by a list of valid cities.
The `cities` query parameter is case-insensitive.
The list of `cities` provided by your RETS vendor or MLS can
be seen by sending an `OPTIONS` request to the `/properties`
endpoint:
`curl -XOPTIONS -u simplyrets:simplyrets
https://api.simplyrets.com/openhouses`
explode: true
schema:
type: array
items:
type: string
- required: false
in: query
name: vendor
description: |
Specify the RETS vendor to search. This parameter is
**required on multi-mls accounts**. You can query one
vendor at a time. Your vendor IDs can be found in your
account panel, or you can make an HTTP OPTIONS request to
https://api.simplyrets.com.
```
curl -XOPTIONS https://api.simplyrets.com/properties
```
schema:
type: string
- required: false
in: query
name: brokers
description: |
Filter open houses by brokerage with a Broker ID. You can specific
multiple broker parameters. Note, the Broker ID is provided by your
RETS vendor or MLS.
explode: true
schema:
type: array
items:
type: string
- required: false
in: query
name: agent
description: |
Filter the open houses returned by an agent ID. Note, the
Agent ID is provided by your RETS vendor or MLS.
schema:
type: string
- required: false
in: query
name: minprice
description: |
Filter open houses by the minimum price of it's corresponding listing.
schema:
type: integer
- required: false
in: query
name: maxprice
description: |
Filter open houses by the maximum price of it's corresponding listing.
schema:
type: integer
- in: query
name: startdate
description: Scheduled date and time of the open house showing
schema:
type: string
format: date-time
- required: false
in: query
name: lastId
description: |
Used as a cursor for pagination.
schema:
type: integer
- required: false
in: query
name: minarea
description: |
Filter open houses by the minimum living area of it's corresponding
listing.
schema:
type: integer
- required: false
in: query
name: minbeds
description: |
Filter open houses by the minimum number bedrooms of it's
corresponding listing.
schema:
type: integer
- required: false
in: query
name: minbaths
description: |
Filter open houses by the minimum number of bathrooms of it's
corresponding listing.
schema:
type: integer
- required: false
in: query
name: offset
description: |
Increase the offset parameter by the limit to go to the
next "page" of listings. Also take a look at the Link HTTP
Header for pre-built pagination.
*NOTE:* Use the `lastId` parameter for pagination.
schema:
type: integer
- required: false
in: query
name: limit
description: |
The number of records returned in the API response. This
can be set to any number between 1 and 500.
The default limit is 12 on the `/openhouses` endpoint.
schema:
type: integer
- required: false
in: query
name: sort
description: |
Sort the response by a specific field. Values starting
with a minus (-) denote descending order, while the others
are ascending.
schema:
type: string
enum:
- listprice
- '-listprice'
- listdate
- '-listdate'
- beds
- '-beds'
- baths
- '-baths'
- required: false
in: query
name: include
description: >
Include a extra fields which are not in the default
response body. Available values:
- 'rooms': include parameter will include
any additional rooms as a list.
Note that your RETS vendor or MLS must provide these
fields in their RETS data for them to be available in the
API response. In the future, fields which require an
'include' may become available by default.
explode: true
schema:
type: array
items:
type: string
description: |
This is the main endpoint for accessing openhouses.
'/openhouses/{openHouseKey}':
get:
summary: Single OpenHouse Endpoint
tags:
- OpenHouses
responses:
'200':
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`
content:
application/json:
schema:
$ref: '#/components/schemas/OpenHouse'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/OpenHouse'
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- required: true
in: path
name: openHouseKey
description: A unique OpenHouse identification key
schema:
type: integer
format: int64
default: 189018
- required: false
in: query
name: vendor
description: |
Specify the RETS vendor to search. This parameter is
**required on multi-mls accounts**. You can query one
vendor at a time. Your vendor IDs can be found in your
account panel, or you can make an HTTP OPTIONS request to
https://api.simplyrets.com.
```
curl -XOPTIONS https://api.simplyrets.com/properties
```
schema:
type: string
- required: false
in: query
name: include
description: |
Include a extra fields which are not in the default
response body. Available values:
- 'rooms': include parameter will include
any additional rooms as a list.
Note that your RETS vendor or MLS must provide these
fields in their RETS data for them to be available in the
API response. In the future, fields which require an
'include' may become available by default.
explode: true
schema:
type: array
items:
type: string
description: |
Use this endpoint for accessing a single OpenHouse.
/properties:
get:
summary: The SimplyRETS listings API
tags:
- Listings
responses:
'200':
headers:
X-SimplyRETS-LastUpdate:
description: >-
The last time a listing refresh was completed for the RETS
or WebAPI feed associated with this API request.
schema:
type: timestamp
Link:
description: A set of pagination headers provided by the SimplyRETS API.
schema:
type: string
X-Total-Count:
description: |
The total number of listings that match this search.
In many cases this number will be higher than the
total number of listings included in the response
body.
_This header is only returned when `count=true`
is specified in the query._
schema:
type: timestamp
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Listing'
type: array
application/vnd.simplyrets-v0.1+json:
schema:
items:
$ref: '#/components/schemas/Listing'
type: array
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- "$ref": "#/components/parameters/q"
- "$ref": "#/components/parameters/status"
- "$ref": "#/components/parameters/type"
- "$ref": "#/components/parameters/subtype"
- "$ref": "#/components/parameters/subTypeText"
- "$ref": "#/components/parameters/agent"
- "$ref": "#/components/parameters/coListAgent"
- "$ref": "#/components/parameters/salesAgent"
- "$ref": "#/components/parameters/brokers"
- "$ref": "#/components/parameters/specialListingConditions"
- "$ref": "#/components/parameters/ownership"
- "$ref": "#/components/parameters/minprice"
- "$ref": "#/components/parameters/maxprice"
- "$ref": "#/components/parameters/minarea"
- "$ref": "#/components/parameters/maxarea"
- "$ref": "#/components/parameters/minbaths"
- "$ref": "#/components/parameters/maxbaths"
- "$ref": "#/components/parameters/minbeds"
- "$ref": "#/components/parameters/maxbeds"
- "$ref": "#/components/parameters/maxdom"
- "$ref": "#/components/parameters/minlistdate"
- "$ref": "#/components/parameters/maxlistdate"
- "$ref": "#/components/parameters/minyear"
- "$ref": "#/components/parameters/maxyear"
- "$ref": "#/components/parameters/minacres"
- "$ref": "#/components/parameters/maxacres"
- "$ref": "#/components/parameters/minGarageSpaces"
- "$ref": "#/components/parameters/maxGarageSpaces"
- "$ref": "#/components/parameters/limit"
- "$ref": "#/components/parameters/offset"
- "$ref": "#/components/parameters/lastId"
- "$ref": "#/components/parameters/vendor"
- "$ref": "#/components/parameters/postalCodes"
- "$ref": "#/components/parameters/features"
- "$ref": "#/components/parameters/exteriorFeatures"
- "$ref": "#/components/parameters/water"
- "$ref": "#/components/parameters/neighborhoods"
- "$ref": "#/components/parameters/cities"
- "$ref": "#/components/parameters/state"
- "$ref": "#/components/parameters/counties"
- "$ref": "#/components/parameters/points"
- "$ref": "#/components/parameters/idx"
- "$ref": "#/components/parameters/include"
- "$ref": "#/components/parameters/sort"
- "$ref": "#/components/parameters/count"
description: |
This is the main endpoint for accessing your properties. View
all of the available query parameters and make requests below!
The API uses Basic Authentication, which most HTTP libraries
will handle for you. To use the test data (which is what this
pages uses), you can use the api key `simplyrets` and secret
`simplyrets`. Note that these test listings are not live RETS
listings but the data, query parameters, and response bodies
will all work the same.
options:
summary: Get metadata for the properties in a particular feed
tags:
- Metadata
responses:
'200':
headers:
X-SimplyRETS-Media-Type:
description: API version of the request and response.
schema:
type: string
description: |
A successful request will return a 200 OK status code
and a JSON response body.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/PropertiesOptionsResponse'
application/vnd.simplyrets-v0.1+json:
schema:
type: object
$ref: '#/components/schemas/PropertiesOptionsResponse'
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- "$ref": "#/components/parameters/vendor"
description: |
An `OPTIONS` request to the `/properties` endpoint will
return general information about the underlying RETS or
WebAPI feed. This information is useful for a lot of
use-cases, like generating pages and queries for the cities
available the data.
**Note**: If you have multiple feeds connected to your app,
you must use a `vendor` parameter with this request.
/:
options:
summary: Get information about the current API credentials
tags:
- Metadata
responses:
'200':
headers:
X-SimplyRETS-Media-Type:
description: API version of the request and response.
schema:
type: string
description: |
A successful request will return a 200 OK status code
and a JSON response body.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/OptionsResponse'
application/vnd.simplyrets-v0.1+json:
schema:
type: object
$ref: '#/components/schemas/OptionsResponse'
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
description: |
Making an OPTIONS reqeust to the API root endpoint
(`api.simplyrets.com/`) returns information about the
current API credentials, like available vendors and the time
of their last sync, available endpoints, and more.
'/properties/{mlsId}':
get:
summary: Single listing endpoint
tags:
- Listings
responses:
'200':
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Listing'
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- required: true
in: path
name: mlsId
description: |
The `mlsId` field is a unique identifier which is specific
to the SimplyRETS API only. This field is different from
the `listingId` field (which is the public number given to
a listing by the RETS vendor or MLS and is not used here).
schema:
type: integer
format: int64
default: 1005252
- required: false
in: query
name: vendor
description: |
Specify the RETS vendor to search. This parameter is
**required on multi-mls accounts**. You can query one
vendor at a time. Your vendor IDs can be found in your
account panel, or you can make an HTTP OPTIONS request to
https://api.simplyrets.com.
```
curl -XOPTIONS https://api.simplyrets.com/properties
```
schema:
type: string
- required: false
in: query
name: include
description: >
Include a extra fields which are not in the default
response body. Available values:
- 'rooms': include parameter will include
any additional rooms as a list.
Note that your RETS vendor or MLS must provide these
fields in their RETS data for them to be available in the
API response. In the future, fields which require an
'include' may become available by default.
explode: true
schema:
type: array
items:
type: string
enum:
- association
- agreement
- garageSpaces
- maintenanceExpense
- parking
- pool
- rooms
description: |
Use this endpoint for accessing a single listing. When you
make a search to the `/properties` endpoint, each listing in
the response will contain a unique `mlsId` field which should
be used to request that listing on this route.
The `mlsId` field is a unique identifier for a listing which
is specific to the SimplyRETS API only. It is different from
the `listingId` field is the public number given to a listing
by the RETS vendor or MLS and is not used here.
/agents:
get:
summary: The SimplyRETS agents API
tags:
- Agents
responses:
'200':
headers:
Link:
description: A set of pagination headers provided by the SimplyRETS API.
schema:
type: string
X-SimplyRETS-LastUpdate:
description: >-
The last time a listing refresh was run for the RETS feed
associated w/ this API request.
schema:
type: timestamp
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AgentsResponse'
type: array
application/vnd.simplyrets-v0.1+json:
schema:
items:
$ref: '#/components/schemas/AgentsResponse'
type: array
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- "$ref": "#/components/parameters/agentQ"
- required: false
in: query
name: name
schema:
type: string
description: |
Filter agents by name. You can provide a first name, last
name, or both.
- required: false
in: query
name: state
schema:
type: string
description: |
Filter agents by their `address.state` field.
description: |
The SimplyRETS agents API allows you to query the agent roster
and data from your RETS feed. This can be useful for building
multiple agent websites for a brokerage, marketing to agents,
and much much more. This endpoint is accessible by adding the
Agents API addon to your app.
/properties/analytics:
get:
summary: The SimplyRETS market analytics API
tags:
- Analytics
responses:
'200':
headers:
Link:
description: A set of pagination headers provided by the SimplyRETS API.
schema:
type: string
X-SimplyRETS-LastUpdate:
description: >-
The last time a listing refresh was run for the RETS feed
associated w/ this API request.
schema:
type: timestamp
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`.
content:
application/json:
schema:
$ref: '#/components/schemas/ListingsAnalytics'
type: object
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/ListingsAnalytics'
type: object
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- "$ref": "#/components/parameters/q"
- "$ref": "#/components/parameters/status"
- "$ref": "#/components/parameters/type"
- "$ref": "#/components/parameters/subtype"
- "$ref": "#/components/parameters/agent"
- "$ref": "#/components/parameters/salesAgent"
- "$ref": "#/components/parameters/brokers"
- "$ref": "#/components/parameters/minprice"
- "$ref": "#/components/parameters/maxprice"
- "$ref": "#/components/parameters/minarea"
- "$ref": "#/components/parameters/maxarea"
- "$ref": "#/components/parameters/minbaths"
- "$ref": "#/components/parameters/maxbaths"
- "$ref": "#/components/parameters/minbeds"
- "$ref": "#/components/parameters/maxbeds"
- "$ref": "#/components/parameters/maxdom"
- "$ref": "#/components/parameters/minyear"
- "$ref": "#/components/parameters/maxyear"
- "$ref": "#/components/parameters/minacres"
- "$ref": "#/components/parameters/maxacres"
- "$ref": "#/components/parameters/minGarageSpaces"
- "$ref": "#/components/parameters/maxGarageSpaces"
- "$ref": "#/components/parameters/limit"
- "$ref": "#/components/parameters/offset"
- "$ref": "#/components/parameters/lastId"
- "$ref": "#/components/parameters/vendor"
- "$ref": "#/components/parameters/postalCodes"
- "$ref": "#/components/parameters/features"
- "$ref": "#/components/parameters/exteriorFeatures"
- "$ref": "#/components/parameters/water"
- "$ref": "#/components/parameters/neighborhoods"
- "$ref": "#/components/parameters/cities"
- "$ref": "#/components/parameters/counties"
- "$ref": "#/components/parameters/points"
- "$ref": "#/components/parameters/idx"
- "$ref": "#/components/parameters/include"
- "$ref": "#/components/parameters/sort"
- "$ref": "#/components/parameters/count"
description: The SimplyRETS Market Analytics API allows you to get high-level
statistics and details about a search query. The `/properties/analytics` endpoint
works the same as `/properties`, but instead of returning listings it returns
analytics. You can use this information to populate details about a specific
area, query, price range, and more, on your website or application.
/properties/{mlsId}/analytics:
get:
summary: The single listing analytics API
tags:
- Analytics
responses:
'200':
headers:
Link:
description: A set of pagination headers provided by the SimplyRETS API.
schema:
type: string
X-SimplyRETS-LastUpdate:
description: >-
The last time a listing refresh was run for the RETS feed
associated w/ this API request.
schema:
type: timestamp
description: |
Will send `Authenticated` if authentication is succesful,
otherwise it will send `Unauthorized`.
content:
application/json:
schema:
$ref: '#/components/schemas/ListingAnalytics'
type: object
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/ListingAnalytics'
type: object
'400':
description: Will send `Bad Request`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Will send `Authentication Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Will send `Authorization Required`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: |
Will send `Too Many Requests`. Please see our Service
Level Agreement for more information on Request Rates and
Acceptable Use.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Will send `Internal Server Error`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.simplyrets-v0.1+json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- required: true
in: path
name: mlsId
description: |
The `mlsId` field is a unique identifier which is specific
to the SimplyRETS API only. This field is different from
the `listingId` field (which is the public number given to
a listing by the RETS vendor or MLS and is not used here).
schema:
type: integer
format: int64
default: 1005252
- "$ref": "#/components/parameters/vendor"
description: Use this endpoint access the analytics for a single listing in
the SimplyREST API. The `/properties/{mlsId}/analytics` endpoint is similar
to the `/properties/{mlsId}` endpoint in that it's used to get the information
for a single listing based on the SimplyRETS unique ID `.mlsId`.
servers:
- url: 'https://api.simplyrets.com/'
security:
- basicAuth: []
components:
securitySchemes:
basicAuth:
in: header
name: Authorization
type: http
description: HTTP Basic Authentication. Works over `HTTPS` only
scheme: basic
parameters:
q:
required: false
in: query
name: q
description: |
A textual keyword search. This parameter will search the following
fields, when available:
- listingId (MLS #)
- street number
- street name
- unit number
- city
- postal code
- subdivision name
- mls area (major)
The `q` parameter can be specified multiple times in a
query. For example, `q=Houston&q=mlsid_12345`.
schema:
type: array
items:
type: string
status:
required: false
in: query
name: status
description: >
Request listings by a specific status. This parameter
defaults to active and you can specify multiple statuses
in a single query.
Listing statuses depend on your RETS vendor's field
availability. Below is a brief description of each status
with possible synonyms which may map to your RETS
vendor-specific statuses.
- **Active**: Active Listing which is still on the market
- **ActiveUnderContract**: An offer has been accepted but the listing
is still on market. Synonyms: Accepting Backup Offers, Backup Offer,
Active With Accepted. Synonyms: Offer, Backup, Contingent
- **Pending**: An offer has been accepted and the listing is no longer
on market. Synonyms: Offer Accepted, Under Contract
- **ComingSoon**: This is a listing that has not yet been on
market but will be on market soon.
- **Closed**: The purchase agreement has been fulfilled or the lease
agreement has been executed. Synonyms: Sold, Leased, Rented, Closed Sale
explode: true
schema:
type: array
items:
type: string
enum:
- Active
- Pending
- Closed
- ActiveUnderContract
- Hold
- Withdrawn
- Expired
- Delete
- Incomplete
- ComingSoon
type:
required: false
in: query
name: type
description: |
Request listings by a specific property type. This
defaults to Residential and Rental. You can specify
multiple property types in a single query.
explode: true
schema:
type: array
items:
type: string
enum:
- residential
- rental
- mobilehome
- condominium
- multifamily
- commercial
- commerciallease
- land
- farm
subtype:
required: false
in: query
name: subtype
description: |
Request listings by a specific property sub type.
*NOTE* not all sub type filters are available for all vendors.
explode: true
schema:
type: array
items:
type: string
enum:
- apartment
- boatslip
- singlefamilyresidence
- deededparking
- cabin
- condominium
- duplex
- manufacturedhome
- ownyourown
- quadruplex
- stockcooperative
- townhouse
- timeshare
- triplex
- manufacturedonland
- farmandranch
- agriculture
- business
- hotelmotel
- industrial
- mixeduse
- officespace
- retail
- unimprovedland
- warehouse
subTypeText:
required: false
in: query
name: subTypeText
description: |
Filter listings by `.property.subTypeText`. The `subTypeText`
is the original MLS SubType value. This parameter can be used
multiple times.
Please refer to your MLS for an exact list of possible values.
explode: true
schema:
type: array
items:
type: string
agent:
required: false
in: query
name: agent
description: |
Filter the listings returned by the `listAgent` id. Note, the
Agent ID is provided by your RETS vendor or MLS.
The co-listing agent is not included in this query parameter.
explode: true
schema:
type: array
items:
type: string
coListAgent:
required: false
in: query
name: coListAgent
description: |
Filter the listings returned by the CoListAgent (`.coAgent.id`) field.
Note, the CoListAgent ID is provided by the MLS.
The primary ListAgent is not included in this query parameter.
explode: true
schema:
type: array
items:
type: string
salesAgent:
required: false
in: query
name: salesAgent
description: >
Filter the listings returned by the `sales.agent` id. Note, the
Agent ID is provided by your RETS vendor or MLS.
The co-sales or co-buyer's agent is not included in this query
parameter.
explode: true
schema:
type: array
items:
type: string
brokers:
required: false
in: query
name: brokers
description: |
Filter the listings returned by brokerage with a Broker
ID. For some MLS areas, this is the ListOfficeId (Listing
Office ID). You can specific multiple broker
parameters. Note, this query parameter is only available
if a Broker ID is provided by your RETS vendor or MLS.
explode: true
schema:
type: array
items:
type: string
specialListingConditions:
required: false
in: query
name: specialListingConditions
description: |
Filter the listings by special listing conditions like REO,
Short Sale, Auction, etc.
Note: The available `specialListingConditions` values are
dependent on the data provided by your MLS.
explode: true
schema:
type: array
items:
type: string
ownership:
required: false
in: query
name: ownership
description: |
Filter listings by the `ownership` field.
Note: The possible values for this field varies. Consult your
MLS for a list of available `ownership` values.
explode: true
schema:
type: array
items:
type: string
minprice:
required: false
in: query
name: minprice
description: |
Filter listings by a minimum price.
schema:
type: integer
maxprice:
required: false
in: query
name: maxprice
description: |
Filter listings by a maximum price
schema:
type: integer
minarea:
required: false
in: query
name: minarea
description: |
Filter listings by a minimum area size in Sq Ft.
schema:
type: integer
maxarea:
required: false
in: query
name: maxarea
description: |
Filter listings by a maximum area size in Sq Ft.
schema:
type: integer
minbaths:
required: false
in: query
name: minbaths
description: |
Filter listings by a minimum number of bathrooms.
schema:
type: integer
maxbaths:
required: false
in: query
name: maxbaths
description: |
Filter listings by a maximum number of bathrooms.
schema:
type: integer
minbeds:
required: false
in: query
name: minbeds
description: |
Filter listings by a minimum number of bedrooms.
schema:
type: integer
maxbeds:
required: false
in: query
name: maxbeds
description: |
Filter listings by a maximum number of bedrooms.
schema:
type: integer
maxdom:
required: false
in: query
name: maxdom
description: |
Filter listings by a maximum number of days on market. _Note
that your RETS vendor or MLS must provide Days on Market data._
schema:
type: integer
minyear:
required: false
in: query
name: minyear
description: |
Filter listings by a setting a minimum year built.
schema:
type: integer
maxyear:
required: false
in: query
name: maxyear
description: |
Filter listings by a setting a maximum year built.
schema:
type: integer
minacres:
required: false
in: query
name: minacres
description: |
Filter listings by a setting a minimum acreage.
schema:
type: integer
maxacres:
required: false
in: query
name: maxacres
description: |
Filter listings by a setting a maximum acreage.
schema:
type: integer
minGarageSpaces:
required: false
in: query
name: minGarageSpaces
description: |
Filter listings by a minimum number of garage spaces.
schema:
type: integer
maxGarageSpaces:
required: false
in: query
name: maxGarageSpaces
description: |
Filter listings by a maximum number of garage spaces.
schema:
type: integer
minlistdate:
required: false
in: query
name: minlistdate
description: |
Query listings with a `.listDate` _after_ (or equal to) this value.
**Note:** By default this is parsed and compared as UTC unless
a timezone is specified in the parameter.
schema:
type: string
maxlistdate:
required: false
in: query
name: maxlistdate
description: |
Query listings with a `.listDate` _before_ (or equal to) this value.
**Note:** By default this is parsed and compared as UTC unless
a timezone is specified in the parameter.
schema:
type: string
limit:
required: false
in: query
name: limit
description: |
Set the number of listings to return in the response.
This defaults to 20 listings, and can be a maximum of 500.
To paginate through to the next page of listings, take a
look at the `offset` parameter, or the Link in the HTTP
Header.
schema:
type: integer
offset:
required: false
in: query
name: offset
description: |
Increase the offset parameter by the limit to go to the
next "page" of listings. Also take a look at the Link HTTP
Header for pre-built pagination.
*NOTE:* Use the `lastId` field to paginate response
*NOTE:* If you're offset is too high, you will receive an
`HTTP 400 offset too high` error message.
schema:
type: integer
lastId:
required: false
in: query
name: lastId
description: >
Used as a cursor for pagination. When using `lastId`, the `sort`
parameter
will not work.
schema:
type: integer
vendor:
required: false
in: query
name: vendor
description: |
Used to specify the RETS vendor to search from. This
parameter is required on multi-MLS apps. You can query one
vendor at a time. To get your vendor id's make an HTTP
OPTIONS request to https://api.simplyrets.com.
`curl -XOPTIONS https://api.simplyrets.com/properties`
schema:
type: string
postalCodes:
required: false
in: query
name: postalCodes
description: |
Filter the listings returned by postal codes / zip
code. You can specify multiple.
explode: true
schema:
type: array
items:
type: string
features:
required: false
in: query
name: features
description: >
Filter the listings by specific **interior features**. You
can use the parameter multiple times to filter by multiple
features. For example, to search for `Wet Bar` and `High
Ceiling`:
```
https://simplyrets.com/services?features=Wet%20Bar&features=High%20Ceiling
```
The list of `features` provided by your RETS vendor or MLS
can be seen by sending an `OPTIONS` request to the
`/properties` endpoint:
```
curl -XOPTIONS -u simplyrets:simplyrets https://api.simplyrets.com/properties
```
explode: true
schema:
type: array
items:
type: string
exteriorFeatures:
required: false
in: query
name: exteriorFeatures
description: >
Filter the listings by specific **exterior features**. You
can use the parameter multiple times to filter by multiple
features. For example, to search for `Proch` and `Fully
Fenced`:
```
https://simplyrets.com/services?exteriorFeatures=Porch&exteriorFeatures=Fully+Fenced
```
explode: true
schema:
type: array
items:
type: string
water:
required: false
in: query
name: water
description: >
Filter listings on WaterBodyName (`.property.water`). There
are multiple ways to use this parameter:
- `water=true`: Return listings where `.property.water` is NOT
`false` or `null`.
- `water=false`: Return listings where `.property.water` is
`false` or `null`.
- `water=QUERY`: Return listings with a matching
`.property.water` value.
If this parameter is used multiple times in a single query,
return listings that match any of the provided values.
schema:
type: array
items:
type: string
neighborhoods:
required: false
in: query
name: neighborhoods
description: >
Filter the listings returned by specific neighborhoods and
subdivisions. You can specify multiple `neighborhoods` by
using the query parameter multiple times.
The `neighborhoods` query parameter is case-insensitive.
The list of `neighborhoods` provided by your RETS vendor or
MLS can be seen by sending an `OPTIONS` request to the
`/properties` endpoint:
`curl -XOPTIONS -u simplyrets:simplyrets
https://api.simplyrets.com/properties`
explode: true
schema:
type: array
items:
type: string
cities:
required: false
in: query
name: cities
description: >
Filter the listings returned by specific cities. You can
specify multiple `cities` query parameters.
The `cities` query parameter is case-insensitive.
The list of `cities` provided by your RETS vendor or MLS can
be seen by sending an `OPTIONS` request to the `/properties`
endpoint:
`curl -XOPTIONS -u simplyrets:simplyrets
https://api.simplyrets.com/openhouses`
explode: true
schema:
type: array
items:
type: string
state:
required: false
in: query
name: state
description: >
Filter the listings by state or province. You can specify
multiple `state` parameters and the parameter is case
insensitive.
explode: true
schema:
type: array
items:
type: string
counties:
required: false
in: query
name: counties
description: >
Filter the listings returned by specific counties. You can
specify multiple `counties` parameters.
The `counties` query parameter is case-insensitive.
The list of `counties` provided by your RETS vendor or MLS
can be seen by sending an `OPTIONS` request to the
`/properties` endpoint:
`curl -XOPTIONS -u simplyrets:simplyrets
https://api.simplyrets.com/openhouses`
explode: true
schema:
type: array
items:
type: string
points:
required: false
in: query
name: points
description: |
Return listings that are within a set of latitude
longitude coordinates. For example;
```
29.723837,-95.69778
29.938275,-95.69778
29.938275,-95.32974
29.723837,-95.32974
```
Note that some RETS vendors do not provide latitude and
longitude with their listings, which is required for this
parameter to work. In these cases, SimplyRETS offers a
[Geocoding Addon](https://simplyrets.com/services#geocoding).
Check out our
[blog post](https://simplyrets.com/blog/interactive-map-search.html)
on using the `points` parameter to build a map-based app
in javascript.
explode: true
schema:
type: array
items:
type: string
idx:
required: false
in: query
name: idx
description: >
Specify the IDX display requirements for the listings in
the response. The `idx` parameter checks if the
`internetAddressDisplay` and
`internetEntireListingDisplay` for each listing are true
(or `null`) or false based on this setting.
##### **`idx=null`** (default)
- `internetAddressDisplay` must be true
- `internetEntireListingDisplay` must be true
##### **`idx=listing`**
- `internetAddressDisplay` is ignored
- `internetEntireListingDisplay` must be true
##### **`idx=address`**
- `internetAddressDisplay` must be true
- `internetEntireListingDisplay` is ignored
##### **`idx=ignore`**
- `internetAddressDisplay` is ignored
- `internetEntireListingDisplay` is ignored
Learn more about SimplyRETS's [IDX compliance features here](/topics/fields-and-features-for-idx-compliance)
and please check with your MLS or data feed provider on
the rules and requirements for displaying restricted
listings.
explode: true
schema:
type: array
items:
type: string
enum:
- "null"
- listing
- address
- ignore
include:
required: false
in: query
name: include
description: |
Enable additional fields in the API response. The available
`include` values are:
- `include=compliance`: Adds `.compliance` data to the API
response. Compliance data will contain extra fields that
may be required in your IDX display. Please check your MLS's
or association's specific IDX display requirements.
- `include=rooms`: Adds `.rooms` data to the API response.
Rooms data contains additional information about individual
rooms on the property (e.g. bedrooms, living room). Not all
feeds support this extended data. Enabled upon request.
explode: true
schema:
type: array
items:
type: string
enum:
- compliance
- rooms
sort:
required: false
in: query
name: sort
description: |
Sort the response by a specific field. Values starting
with a minus (-) denote descending order, while the others
are ascending.
schema:
type: string
enum:
- listprice
- '-listprice'
- listdate
- '-listdate'
- closedate
- '-closedate'
- beds
- '-beds'
- baths
- '-baths'
count:
required: false
in: query
name: count
description: |
When set to `true`, The `X-Total-Count` header will be
returned, showing the total number of items matching the query.
Counting the listings can contribute to slower API calls
due to the extra queries that need to be run to get an
exact count.
Enabling count may decrease API response/page load times,
especially on larger datasets.
schema:
type: boolean
default: false
agentQ:
required: false
in: query
name: q
description: |
A keyword search on the Agents API. The `q` parameter will
search the `.id` and `.contact.email` fields, and return
listings matching the criteria. `q` can be provided multiple
times.
schema:
type: string
schemas:
Room:
type: object
description: Sales Data
properties:
length:
format: float
type: number
nullable: true
features:
type: string
description: A set of features in the room.
nullable: true
area:
format: float
type: number
description: The area of the room in units provided by the RETS vendor.
nullable: true
width:
format: float
type: number
nullable: true
typeText:
type: string
description: |
Entire raw value of of the room `Type` data provided in the
RETS feed.
nullable: true
type:
type: string
description: The `RoomType` RESO Data Dictionary 1.6 type.
nullable: true
dimensions:
type: string
description: Room dimension textual value.
nullable: true
description:
type: string
description: A description of the room.
nullable: true
StreetAddress:
type: object
description: RETS Street Address
properties:
crossStreet:
type: string
description: Known cross street
nullable: true
state:
type: string
description: >-
State or province. Maps to the data dictionary field
`StateOrProvince`.
nullable: true
country:
type: string
description: Street address country (United States or Canada)
nullable: true
postalCode:
type: string
description: Street Address postal code
nullable: true
streetName:
type: string
description: Name of the street
nullable: true
streetNumberText:
type: string
description: |
Textual representation of the street number. This field
is usually redundant with what's in `streetNumber` but is
occassionally usefuly for street number which are actually
alpha-numerical. For example, "N63453" or "34556B".
**Added on 2016/05/02**
nullable: true
city:
type: string
description: City name
nullable: true
streetNumber:
format: int64
type: integer
description: Street number
nullable: true
full:
type: string
description: Full pretty-printed address with suffix (if available)
nullable: true
unit:
type: string
description: Unit number
nullable: true
Property:
type: object
description: Rets Listing Property
properties:
roof:
type: string
description: Property roof description
nullable: true
cooling:
type: string
description: >-
A description of the cooling or air conditioning features of the
property.
nullable: true
style:
type: string
description: Property style description or short string
nullable: true
area:
format: int64
type: integer
description: Square footage of the building associated with a listing
nullable: true
bathsFull:
format: int64
type: integer
nullable: true
description: Number of full bathrooms
bathsHalf:
format: int64
type: integer
nullable: true
description: Number of half bathrooms
stories:
format: float
type: number
nullable: true
description: |
Number of stories or levels. Represented as a `double' to
account for half stories.
fireplaces:
format: int64
type: integer
nullable: true
description: Number of fireplaces
flooring:
type: string
nullable: true
description: The type(s) of flooring found within the property.
heating:
type: string
description: Heating description or short string
nullable: true
bathrooms:
format: string
description: Total number of bathrooms.
nullable: true
foundation:
type: string
nullable: true
poolFeatures:
type: string
nullable: true
laundryFeatures:
type: string
nullable: true
occupantName:
type: string
nullable: true
ownerName:
type: string
nullable: true
lotDescription:
type: string
nullable: true
acres:
format: float
type: number
description: Lot size in acres
nullable: true
subType:
type: string
enum:
- Apartment
- BoatSlip
- SingleFamilyResidence
- DeededParking
- Cabin
- Condominium
- Duplex
- ManufacturedHome
- Quadruplex
- StockCooperative
- Townhouse
- Timeshare
- Triplex
- ManufacturedOnLand
- null
description: |
A normalized representation of the listings sub-type.
nullable: true
bedrooms:
format: int64
type: integer
description: Number of bedrooms
nullable: true
interiorFeatures:
type: string
description: The properties interior features
nullable: true
lotSize:
type: string
description: |
Lot size dimensions or square footage as a text. This
field is generally used to show the pretty formatted
lot size.
nullable: true
areaSource:
type: string
nullable: true
maintenanceExpense:
format: float
type: number
description: Yearly maintenance expense
nullable: true
additionalRooms:
type: string
description: |
Additional room information. This is a textual description
of additional rooms for the listing.
nullable: true
exteriorFeatures:
type: string
description: |
Exterior Features for the listing
nullable: true
water:
type: string
description: |
The name, if known, of the body of water on which the
property is located. (E.g., lake name, river name, ocean
name, sea name, canal name). Otherwise, this field will
contain features of the waterfront on which the property is
located.
nullable: true
view:
type: string
description: View details and description
nullable: true
lotSizeArea:
format: float
type: number
description: |
The total area of the lot. See `lotSizeUnits` for the units
of measurement (Square Feet, Square Meters, Acres, etc.).
**Added on 2016/05/04 - Not available for all RETS vendors**
nullable: true
subdivision:
type: string
description: The subdivision or community name
nullable: true
construction:
type: string
description: The materials that were used in the construction of the property.
nullable: true
subTypeRaw:
type: string
description: |
The raw text representation of the property sub type.
nullable: true
parking:
$ref: '#/components/schemas/Parking'
# TODO test
nullable: true
lotSizeAreaUnits:
type: string
description: |
Unit of measurement for the lotSizeArea field. e.g. Square
Feet, Square Meters, Acres, etc.
If this field is `null` the units is the default unit
of measure specified by your RETS provider.
**Added on 2016/05/04 - Not available for all RETS vendors**
nullable: true
type:
type: string
enum:
- RES
- CND
- RNT
- MLF
- CRE
- CLE
- LND
- FRM
description: >
The abbreviated property type.
- **RES**: Residential
- **CND**: CondoOrTownhome
- **RNT**: Rental
- **MLF**: MultiFamily
- **CRE**: Commercial
- **CLE**: Commercial Lease
- **LND**: Land
- **FRM**: Farm
Also see the `.property.subType` and
`.property.subTypeText` fields for more information about
the type of property.
garageSpaces:
format: float
type: number
description: Number of garage spaces
nullable: true
bathsThreeQuarter:
format: int64
type: integer
description: Number of 3/4 bathrooms
nullable: true
accessibility:
type: string
nullable: true
occupantType:
type: string
nullable: true
yearBuilt:
format: int64
type: integer
description: Year the property was built
nullable: true
rooms:
items:
$ref: '#/components/schemas/Room'
type: array
nullable: true
description: |
A comprehensive list of rooms. Room data is not included in the
standard payload. Use `include=rooms` in your query to include
room data. If the list of rooms is empty, your RETS vendor may
not supply this information with your RETS feed.
This data is populated from 2 sources:
1. Inline room mappings in the `Property` resource
2. In an external RETS resource (e.g. `Room`)
Listing:
type: object
description: RETS Listing Property
properties:
privateRemarks:
type: string
description: Agent only remarks
nullable: true
property:
$ref: '#/components/schemas/Property'
description: Specific property data associated with listing.
mlsId:
format: int64
type: integer
description: |
A unique identifier for this listing specific to the
SimplyRETS API. Thie identifier is specific to the
SimplyRETS api and has no correlation with the MLS
number. Use this id when making requests to the single
listing endpoint (eg, `/properties/{mlsId}`).
Applications should not rely on specific `mlsId`s being
present. Instead, apps should dynamically use the `mlsId`
after using other more general query parameters. Many mls
vendors require listings which are expired, terminated or
sold to be purged, which will render calls to specific
`mlsId`s to return nothing (or possibly a 404).
showingInstructions:
type: string
description: Public instructions for showing the property.
nullable: true
showingContactName:
type: string
description: The name of the contact for the showing of the listed property.
nullable: true
showingContactPhone:
type: string
description: Telephone number that should be called to arrange showing the property.
nullable: true
specialListingConditions:
type: string
description: |
A list of options that describe the type of sale. i.e. Standard,
REO, Short Sale, Probate, Auction, NOD, etc., at the time of listing.
nullable: true
example: Real Estate Owned
ownership:
type: string
description: |
A text description of the manner in which title to a
property is held. Trust, Corporation, Joint Tennant,
Individual.
nullable: true
example: Individual
office:
$ref: '#/components/schemas/Office'
description: Listing office or brokerage.
nullable: true
leaseTerm:
type: string
description: Represents the length of the lease.
nullable: true
disclaimer:
type: string
description: |
Data accuracy disclaimer. The value in the disclaimer may
change depending on the rules imposed by your RETS vendors.
nullable: true
address:
$ref: '#/components/schemas/StreetAddress'
description: Comprehensive property address information
nullable: true
listDate:
format: date-time
type: string
description: Date and time the listing became Active
nullable: true
agent:
$ref: '#/components/schemas/Agent'
description: Comprehensive listing agent information
nullable: true
modified:
format: date-time
type: string
description: Date and time of the last modification
nullable: true
school:
$ref: '#/components/schemas/School'
description: Comprehensive school zone data
nullable: true
photos:
items:
type: string
type: array
description: |
Photos of the property. Images are served over https and are
suitable for production use on secure websites
listPrice:
format: double
type: number
description: Price of the listing
nullable: true
originalListPrice:
format: double
type: number
description: |
The original price of the property on the initial
agreement between the seller and the seller's broker.
nullable: true
internetAddressDisplay:
type: boolean
nullable: true
description: The IDX address display requirements of the listing from the MLS.
listingId:
type: string
description: |
Data Dictionary v1.3 ListingId. The well known identifier for
the listing. The value is the id or number by the RETS vendor
as a public identifier for the listing.
This identifier should not be confused with the `mlsId`, which is
specific to the SimplyRETS API.
mls:
$ref: '#/components/schemas/MlsInformation'
description: RETS vendor information and data
nullable: true
internetEntireListingDisplay:
type: boolean
nullable: true
description: The IDX entire listing display requirements of the listing from the MLS.
geo:
$ref: '#/components/schemas/GeographicData'
description: Geographic data for the listing
nullable: true
tax:
$ref: '#/components/schemas/Tax'
description: Associate tax data
nullable: true
coAgent:
$ref: '#/components/schemas/Agent'
nullable: true
description: |
co-listing agent information.
*NOTE*: If your RETS feed stores co-list information outside
of the `Property` resource, co-list agent information will not
be available.
sales:
$ref: '#/components/schemas/Sales'
description: Sales data
nullable: true
leaseType:
type: string
description: Information about the status of the existing lease on the property.
nullable: true
virtualTourUrl:
type: string
description: |
The URL for an unbranded virtual tour of the property.
**Added on 2016/05/04 - Not available for all RETS vendors**
nullable: true
remarks:
type: string
description: Description or remarks
nullable: true
association:
$ref: '#/components/schemas/Association'
nullable: true
OpenHouse:
type: object
description: SimplyRETS Open House object
properties:
refreshments:
type: string
description: Provided
nullable: true
listing:
$ref: '#/components/schemas/Listing'
description: The full listing associated with the OpenHouse
startTime:
format: date-time
type: string
description: Start Date for the open house
nullable: true
openHouseKey:
type: integer
description: |
A unique identifier for the open house which is specific to the
SimplyRETS API
endTime:
format: date-time
type: string
description: The ending date time for the open house
nullable: true
openHouseId:
type: string
description: |
The MLS number or id provided by the RETS vendor or MLS.
type:
type: string
description: 'The open house type. For example, Public or Private'
nullable: true
description:
type: string
description: The remarks and/or description details for the open house
nullable: true
Office:
type: object
description: RETS Office
properties:
contact:
$ref: '#/components/schemas/ContactInformation'
nullable: true
description: |
Associated contact details for the office. The availability of this
information depends on your RETS vendor's rules and regulations
*Contact information is not available for all RETS Vendors.*
name:
type: string
description: Pimary office name
nullable: true
servingName:
type: string
description: Primary office or brokerage name
nullable: true
brokerid:
type: string
nullable: true
description: |
Office or brokerage MLS identifier
**Not available for all RETS vendors**
ListingAnalytics:
type: object
description: The SimplyRETS single listing analytics API response
properties:
pricePerSqFt:
nullable: true
type: number
format: float
example: 8.25
description: The listing's price per square foot, based on the current `ListPrice`
and `LivingArea`.
ListingsAnalytics:
type: object
description: The SimplyRETS market analytics API response
properties:
avgLivingArea:
nullable: true
type: number
format: float
example: 2550
description: The average `LivingArea` of listings matching the search criteria.
avgFullBaths:
nullable: true
type: number
format: float
example: 2.5
description: The average `BathroomsFull` of listings matching the search criteria.
avgBedrooms:
nullable: true
type: number
format: float
example: 3
description: The average `BedroomsTotal` of listings matching the search criteria.
avgLotSize:
nullable: true
type: number
format: float
example: 9750.25
description: The average `LotSizeArea` of listings matching the search criteria.
avgPrice:
nullable: true
type: number
format: float
example: 325275
description: The average `ListPrice` of listings matching the search criteria.
avgYearBuilt:
nullable: true
type: number
format: float
example: 1990
description: The average `YearBuilt` of listings matching the search criteria.
areaDistribution:
nullable: true
type: object
example:
Other: 0
Towne Lake: 5
Rice Military: 3
Vineyard Mdw Sec 01: 3
Glen Arbor Sec 07: 4
description: The total number of listings in an MLS area matching the search
criteria.
totalCount:
nullable: true
type: integer
example: 15
description: The total number of listings matching the search criteria, and
used to calculate the analytics.
AgentsResponse:
type: object
description: The SimplyRETS agents API response
properties:
id:
nullable: true
type: string
example: 123456789
description: The MLS id of the agent.
firstName:
nullable: true
type: string
example: John
description: The first name of the agent.
lastName:
nullable: true
type: string
example: Doe
description: The last name of the agent.
address:
$ref: '#/components/schemas/StreetAddress'
description: Agent address information
nullable: true
contact:
$ref: "#/components/schemas/ContactInformation"
description: Agent contact information
nullable: true
officeMlsId:
nullable: true
type: string
example: MLS123
description: The local, well-known MLS ID of the agent's office.
OptionsResponse:
type: object
description: Response of a successful OPTIONS request to /
properties:
expires:
nullable: false
type: string
format: date-time
example: "2020-01-02T11:06:18.916879378Z"
description: |
Timestamp of when the information in this response
should be considered stale.
vendors:
type: array
nullable: false
items:
type: string
example: ["abcmls", "xyzmls"]
description: |
A list of vendor IDs available to these API credentials,
to be used in requests to `/properties`, `/openhouses`,
etc.
updates:
type: object
nullable: false
additionalProperties:
type: string
example:
abcmls: "2020-08-01T01:06:18.235819332Z"
xyzmls: "2020-08-01T11:06:18.916879378Z"
description: |
A key/value map of vendor IDs with the timestamp of the
last succesful sync.
endpoints:
nullable: false
type: array
items:
type: string
example: ["/properties", "/openhouses"]
description: |
A list of API endpoints accesible with these credentials.
accepts:
nullable: false
type: array
items:
type: string
example: ["application/json", "application/vnd.simplyrets-v0.1+json"]
description: |
A list of valid media types available to these API credentials.
See [versioning API requests with media types](/topics/versioning-api-requests-with-media-types).
PropertiesOptionsResponse:
type: object
description: Response of a successful OPTIONS request to /properties
properties:
expires:
nullable: false
type: string
format: date-time
example: "2020-01-02T11:06:18.916879378Z"
description: |
Timestamp when the information in this response should
be considered stale.
lastUpdate:
nullable: false
type: string
format: date-time
example: "2020-01-01T11:06:18.916879378Z"
description: |
Timestamp when this feed was last synced with the data
source successfully.
fields:
nullable: true
type: object
description: |
An object containing field names, and all known values
for that field in this feed.
properties:
status:
nullable: true
type: array
items:
type: string
example: ["Active", "Pending", "Closed"]
description: A list of `statuses` available for this feed.
cities:
nullable: true
type: array
items:
type: string
example: ["Houston", "Austin", "Dallas"]
description: A list of `cities` found in this feed.
counties:
nullable: true
type: array
items:
type: string
example: ["Houston", "Austin", "Dallas"]
description: A list of `counties` found in this feed.
features:
nullable: true
type: array
items:
type: string
example: ["Central Air", "Great views", "Patio"]
description: A list of `interiorFeatures` found in this feed.
neighborhoods:
nullable: true
type: array
items:
type: string
example: ["Downtown", "Midtown", "Uptown"]
description: A list of `neighborhoods` found in this feed.
areaMinor:
nullable: true
type: array
items:
type: string
example: ["01-Rice Village", "02-Independence Heights", "03-Garden Oaks"]
description: A list of `areaMinor`s found in this feed.
type:
nullable: true
type: array
items:
type: string
example: ["Residential", "Rental", "Condominium", "Townhome", "Land"]
description: A list of property `type`s found in this feed.
Error:
type: object
description: Error information
properties:
error:
format: int32
type: integer
description: |
Error code. In general, we try to adhere to HTTP status code
and use these error statuses for detailed reporting.
message:
type: string
description: Status message with an explanation of the error
Agent:
type: object
description: SimplyRETS Agent Api
properties:
lastName:
type: string
description: Agent last name
nullable: true
contact:
$ref: '#/components/schemas/ContactInformation'
description: |
Agent contact info. This information is only present when
your RETS feed specifies the agent wishes to show their
contact information publicly.
*Contact information is not available for all RETS Vendors.*
nullable: true
firstName:
type: string
description: Agent first name
nullable: true
id:
type: string
description: Well known Agent MLS number or id.
nullable: true
School:
type: object
description: RETS School Data
properties:
middleSchool:
type: string
description: Middle or junior school name
nullable: true
highSchool:
type: string
description: High school name
nullable: true
elementarySchool:
type: string
description: Elementary school name.
nullable: true
district:
type: string
description: School district name.
nullable: true
ContactInformation:
type: object
description: RETS Contact Information
nullable: true
properties:
email:
type: string
description: |
The email address of the `ContactInformation`
**Not available for all RETS vendors**
nullable: true
office:
type: string
description: |
Contact Information Office Phone Number
**Not available for all RETS vendors**
nullable: true
cell:
type: string
description: |
Contact Information Cell Phone
**Not available for all RETS vendors**
nullable: true
Tax:
type: object
description: RETS Tax Data
properties:
taxYear:
format: int64
type: integer
description: Tax Year
nullable: true
taxAnnualAmount:
type: integer
description: Annual tax amount in USD
nullable: true
id:
type: string
description: Tax Parcel ID for the listing
nullable: true
Parking:
type: object
description: RETS School Data
properties:
leased:
type: string
nullable: true
spaces:
type: integer
description: Number of parking spaces
nullable: true
description:
type: string
description: Parking features description
nullable: true
Sales:
type: object
description: Sales Data
properties:
closeDate:
format: date-time
type: string
description: RETS Sales data close date
nullable: true
office:
$ref: '#/components/schemas/Office'
description: RETS Sales data selling office/brokerage id
nullable: true
closePrice:
format: int64
type: integer
description: RETS Sales data sold price
nullable: true
agent:
$ref: '#/components/schemas/Agent'
description: RETS Sales data agent id
nullable: true
contractDate:
format: date-time
type: string
description: RETS Sales data contract date
nullable: true
GeographicData:
type: object
description: RETS Geographic Data
properties:
county:
type: string
description: Listing county
nullable: true
lat:
format: double
type: number
description: Listing latitude (if available)
nullable: true
lng:
format: double
type: number
description: Listing longitude (if available)
nullable: true
marketArea:
type: string
description: Listing GeoMarket area. May be the same as mlsArea
nullable: true
directions:
type: string
description: Directions to the property
nullable: true
Broker:
type: object
description: SimplyRETS Broker Api
properties:
startdate:
format: date-time
type: string
description: Start Date
nullable: true
MlsInformation:
type: object
description: RETS Vendor Data
properties:
status:
type: string
enum:
- Active
- ActiveUnderContract
- Pending
- Hold
- Withdrawn
- Closed
- Expired
- Delete
- Incomplete
- ComingSoon
description: >
Normalized [RESO Data Dictionary 1.7]() standard status
value. Compliant with Data Dictionary v1.7 `ListingStatus`.
Listing statuses depend on your RETS vendor's field
availability. Below is a brief description of each status
with possible synonyms which may map to your RETS
vendor-specific statuses.
- **Active**: Active Listing which is still on the market
- **ActiveUnderContract**: An offer has been accepted but the listing
is still on market. Synonyms: Accepting Backup Offers, Backup Offer,
Active With Accepted. Synonyms: Offer, Backup, Contingent
- **Pending**: An offer has been accepted and the listing is no longer
on market. Synonyms: Offer Accepted, Under Contract
- **ComingSoon**: This is a listing that has not yet been on
market but will be on market soon.
- **Closed**: The purchase agreement has been fulfilled or the lease
agreement has been executed. Synonyms: Sold, Leased, Rented, Closed Sale
area:
type: string
nullable: true
description: >-
MLS Area major. The major marketing area name, as defined by the MLS
or other non-governmental organization.
daysOnMarket:
format: int64
type: integer
description: Amount of days the property has been Active
nullable: true
originalEntryTimestamp:
format: date-time
type: string
nullable: true
description: |
The transactional timestamp automatically recorded by the MLS system
representing the date/time the listing was entered and made visible
to members of the MLS.
originatingSystemName:
type: string
description: >
Alias for the listing office or brokerage
This field corresponds to the data-dictionary
`OriginatingSystemName` field
The name of the originating record provider. Most commonly
the name of the MLS. The place where the listing is
originally input by the member. The legal name of the
company. To be used for display.
If you're data provider aggregates feeds from multiple other
RETS vendors, this will be the name of the originating RETS
vendor.
nullable: true
statusText:
type: string
description: |
Raw MLS status text. This `field` comes directly from your RETS data
field and is not normalized.
areaMinor:
type: string
description: >-
MLS Area minor. The minor/sub marketing area name, as defined by the
MLS or other non-governmental organization.
nullable: true
Association:
type: object
description: Home Owners Association
properties:
fee:
type: integer
description: Association fee
nullable: true
frequency:
type: string
description: |
The frequency the association fee is paid. For example:
Monthly, Annually, One Time, etc.
nullable: true
name:
type: string
description: Name of the association
nullable: true
amenities:
type: string
description: Any extra amenities granted by the HOA
nullable: true