Example RETS Session
Access to the various parts of a RETS server is handled using HTTP requests to different URLs. The server's responses to those requests are delivered back in the standardized format described in the RETS specification (available at www.rets.org).
Note: There are several free and open source tools that are available that handle the technical aspects of issuing requests and reading responses to and from a RETS server, so many of the more specific details mentioned here are handled automatically behind-the-scenes within most of those tools.
Terminology
Class – Best thought of as a sub category. Examples: The "Property" Resource may have Classes such as "A" for Residential, "B" for Lots and Land, "C" for Residential Rentals, etc. while the "Agent" Resource may have a class such as "Agent". Each Class represents a different fieldset, allowing (for example) Residential to include fields that Land may not need.
Lookup – When a specific field is described as having Lookup values, the content of that field can only contain a pre-determined set of values. To learn what those values are and what they stand for, a request can be made that returns a list of all possible values within that field. An example would be the Listing Status field to learn that the possible values are Active, Pending, Expired, Cancelled, Deleted, etc.
COMPACT – This is one format responses can be returned as (you'll see it used often in the examples below). The contents of these responses are returned back in a tab delimited format. COMPACT-DECODED is a very similar format except that fields containing Lookup values have their codes replaced with their human-readable meanings.
For a full glossary of commonly used terms related to RETS, see www.rets.org/glossary.
Example Session
Below is a sample session which can be run through your web browser to make understanding what's available easier. Viewing the page's source code (from your browser's 'View' menu) will show all characters from the returned response which often times makes more sense than what's displayed to you visually.
- Successfully login
- Discover what Resources are available on the server
- Discover specific Classes for each Resource
- Retrieve detailed field definitions for each of those Classes
- Learn all possible values for the Listing Status field
- Perform a query to retrieve all Residential properties where the Listing Status field shows as Active
- Retrieve the main photo for a returned property
- Retrieve all photos for a returned property
- Logout
(1) Successfully login:
http://retsgw.flexmls.com/rets2_3/Login
You'll be prompted for your username and password. The RETS login URL, username and password were initially provided to you by the MLS. A successful login will establish a cookie which is used to keep your session alive between requests.
(2) Discover Resources available:
http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-RESOURCE&ID=0&Format=COMPACT
The response from this RETS request contains information about all of the Resources available on the RETS server. Note the KeyField for the "Property" Resource (assuming "LIST_1" for the rest of these examples).
(3) Discover specific Classes available:
http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-CLASS&ID=Property&Format=COMPACT
The response contains DATA lines for each Class within the "Property" Resource (see the ID= parameter in the URL). Any future request we're interested in for Residential properties will need to be done using Residential's SystemName (assuming "A").
(4) Retrieve detailed field information:
http://retsgw.flexmls.com/rets2_3/GetMetadata?Type=METADATA-TABLE&ID=Property:A&Format=COMPACT
The response will contain many DATA entries. Each of those entries represents a single field available in that Class. Columns such as DataType and MaximumLength provide details about the specific type of data you can expect to receive in that field. Find the field that represents the Listing Status (assuming "LIST_15"). The "Interpretation" column should indicate that this is a 'Lookup'. Note the LookupName for that field (assuming "20070913202543158090000000").
(5) Learn all possible values for Listing Status:
The response will contain multiple DATA entries, each representing a possible value within the LIST_15 field. Since we're interested in Active listings, note the contents of that row's Value column (assuming "OV61GOJ13C0"). This value is used in the query.
(6) Perform a query:
The response will contain the records you requested (limited to 50 due to the Limit argument given at the end). The COLUMNS line indicates the field names of the records returned and all DATA rows represent the records with field values in the same order as shown by the COLUMN row. If you're only interested in receiving certain fields back, you can add a "&Select=" parameter to the end of the URL. For example, if you only want to retrieve back the KeyName field (noted as "LIST_1") and the Listing Status field (noted as "LIST_15"), add "&Select=LIST_1,LIST_15" to the end of that URL. Note a few 'LIST_1' values for the next example.
(7) Retrieve the main photo:
The ID value in this URL is made up of the value of the KeyField ("LIST_1") associated with your desired record, followed by a colon, followed by a zero (note: the KeyField cannot be assumed to be the MLS# for the property). The final "0" indicates that you'd like the main property photo. The response will contain one of 2 things. If the main photo does not exist, the response will be in XML format as a RETS error. If the main photo does exist, the raw photo data will be returned back (which your web browser should display as the actual photo to you).
(8) Retrieve multiple photos:
This is the same request as the single photo, except that instead of requesting a specific photo for the property (such as "2" for the second photo in the order displayed in the MLS), it's replaced with an * (asterisk). This instructs the RETS server to return all available photos for the given record. This response comes back in a multi-part (MIME) format which allows photo data from multiple images to be returned in a single response. These types of responses aren't usually handled well automatically by a web browser but are very easy for tools that are built to expect them. Those tools generally read the multiple images in the single response and save them in separate image files to be used later.
(9) Logout:
http://retsgw.flexmls.com/rets2_3/Logout