Listings

Listing Display Rules
Each MLS defines rules each application must abide by when displaying listing reports or brief summary data (such as listing search results). Review the Compliance page for details.
The Listings API is used to retrieve listing information and run searches on listings.
  1. Supported Roles
  2. Available Services
    1. Listings
    2. Individual Listing
    3. My, Office, and Company Listings
    4. Nearby Listings
  3. Response Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads? Writes?
IDX Yes No
VOW Yes No
Private Yes No
More information about roles may be found here.

Available Services

Listings

URI: /<API Version>/listings

HTTP Method Description Notes
GET Retrieves listing data
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

GET Response

See the GET response section below for the data format.

Individual Listing

URI: /<API Version>/listings/<Id>

HTTP Method Description Notes
GET Retrieve listing information for a single listing. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

GET Response

Example:
{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listings/20060412165917817933000000",
                "Id": "20060412165917817933000000",
                "StandardFields": {
                    "ListingKey": "20060412165917817933000000",
                    "ListingId": "10-1796",
                    "PropertyType": "A ",
                    "PropertySubType": "SF",
                    "ListPrice": 1079900,
                    "StreetNumber": "611",
                    "StreetDirPrefix": null,
                    "StreetName": "8th",
                    "StreetSuffix": "St",
                    "StreetDirSuffix": "S",
                    "StreetAdditionalInfo": null,
                    "City": "Fargo",
                    "StateOrProvince": "ND",
                    "PostalCode": "58103",
                    "YearBuilt": 1884,
                    "BuildingAreaTotal": 7275,
                    "BathsThreeQuarter": 1,
                    "BathsTotal": 8,
                    "BathsFull": 5,
                    "BedsTotal": 8,
                    "BathsHalf": 2,
                    "Longitude": -96.792246,
                    "Latitude": 46.868464,
                    "SubdivisionName": "Westgate",
                    "MLSAreaMinor": "West",
                    "CountyOrParish": null,
                    "PublicRemarks": "Great foyer. Cool kitchen. 6 fireplaces. The list goes on.",
                    "PrivateRemarks": "********",
                    "PrivateOfficeRemarks": "********",
                    "PendingDate", "********",
                    "CloseDate": "********",
                    "CancelDate": "********",
                    "WithdrawDate": "********",
                    "ListAgentFirstName": "Joe",
                    "ListAgentMiddleName": "",
                    "ListAgentLastName": "Agent",
                    "ListAgentPreferredPhone": "123-456-7890",
                    "ListAgentPreferredPhoneExt": "3",
                    "ListAgentOfficePhone": "123-456-7890",
                    "ListAgentOfficePhoneExt": "123-456-7890",
                    "ListAgentCellPhone": "123-456-7890",
                    "ListAgentDirectPhone": "123-456-7890",
                    "ListAgentTollFreePhone": "123-456-7890",
                    "ListAgentFax": "123-456-7890",
                    "ListAgentPager": "123-456-7890",
                    "ListAgentVoiceMail": "123-456-7890",
                    "ListAgentVoiceMailExt": "123-456-7890",
                    "ListAgentEmail": "joe@joeagent.com",
                    "ListAgentURL": "http://joeagent.com/",
                    "ListAgentStateLicense": "12345",
                    "ListAgentDesignation": "CRS, GRI",
                    "ListOfficeName": "BigBrokerCo",
                    "ListOfficePhone": "987-654-3210",
                    "ListOfficePhoneExt": "33",
                    "ListOfficeFax": "987-654-3210",
                    "ListOfficeEmail": "big@brokerco.com",
                    "ListOfficeURL": "http://bigbrokerco.com",
                    "CoListAgentFirstName": "Jimmy",
                    "CoListAgentMiddleName": "",
                    "CoListAgentLastName": "Agent",
                    "CoListAgentPreferredPhone": "323-456-7890",
                    "CoListAgentPreferredPhoneExt": "3",
                    "CoListAgentOfficePhone": "123-456-7890",
                    "CoListAgentOfficePhoneExt": "123-456-7890",
                    "CoListAgentCellPhone": "123-456-7890",
                    "CoListAgentDirectPhone": "123-456-7890",
                    "CoListAgentTollFreePhone": "123-456-7890",
                    "CoListAgentFax": "123-456-7890",
                    "CoListAgentPager": "123-456-7890",
                    "CoListAgentVoiceMail": "123-456-7890",
                    "CoListAgentVoiceMailExt": "123-456-7890",
                    "CoListAgentEmail": "jimmy@jimmyagent.com",
                    "CoListAgentURL": "http://jimmyagent.com/",
                    "CoListAgentStateLicense": "22345",
                    "CoListAgentDesignation": "CRS, GRI",
                    "CoListOfficeName": "BigBrokerCo",
                    "CoListOfficePhone": "987-654-3210",
                    "CoListOfficePhoneExt": "33",
                    "CoListOfficeFax": "987-654-3210",
                    "CoListOfficeEmail": "big@brokerco.com",
                    "CoListOfficeURL": "http://bigbrokerco.com",
                    "ModificationTimestamp": "2010-11-22T20:09:37Z",
                    "VirtualTourURLBranded": "http://somethirdpartyservice.com/234",
                    "VirtualTourURLUnbranded": "http://somethirdpartyservice.com/345",
                    "Supplement": "Text supplement goes here",
                    "Photos": [
                        {
                            "ResourceUri": "/vX/listings/20060412165917817933000000/photos/20080917142739989238000000",
                            "Id": "20080917142739989238000000",
                            "Name": "Listing Photo",
                            "Caption": "",
                            "UriThumb": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-t.jpg",
                            "Uri300": "http://photos.sparkplatform.com/demomls/20080917142739989238000000.jpg",
                            "Uri640": "http://resize.sparkplatform.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
                            "Uri800": "http://resize.sparkplatform.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
                            "Uri1024": "http://resize.sparkplatform.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
                            "Uri1280": "http://resize.sparkplatform.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
                            "Uri1600": "http://resize.sparkplatform.com/demomls/1600x1280/true/20080917142739989238000000-o.jpg",
                            "Uri2048": "http://resize.sparkplatform.com/demomls/2048x1536/true/20080917142739989238000000-o.jpg",
                            "UriLarge": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-o.jpg",
                            "Primary": true
                        }
                    ],
                    "OpenHouses": [
                        {
                            "ResourceUri": "/vX/listings/20060412165917817933000000/openhouses/10000000000000000000000000",
                            "Id": "10000000000000000000000000",
                            "Date": "2007-07-08",
                            "StartTime": "9:00 am",
                            "EndTime": "1:00 pm"
                        }
                    ],
                    "Documents": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/documents/20101125153422574618000000",
                            "Id": "20101125153422574618000000",
                            "Name": "Document name",
                            "Uri": "http://documents.sparkplatform.com/abc.pdf"
                        }
                    ],
                    "VirtualTours": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/virtualtours/20101213041526458274000000",
                            "Id": "20101213041526458274000000",
                            "Name": "VT name",
                            "Uri": "http://somethirdpartyvtservice.com/123",
                            "Type": "branded"
                        }
                    ],
                    "Videos": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/videos/20101213041526458274000000",
                            "Id": "20101213041526458274000000",
                            "Name": "Video name",
                            "Caption": "Caption text",
                            "Type": "branded",
                            "ObjectHtml": "<>"
                        }
                    ],
                    "CustomFields": [
                        {
                            "Main": [
                                {
                                    "Contract Information": [
                                        {
                                            "Book Section": "Residential w/ Acreage"
                                        },
                                        {
                                            "Area": "North (Bonner & Boundary)"
                                        },
                                        {
                                            "Begin Date": "2006-03-03"
                                        }
                                    ]
                                },
                                {
                                    "General Property Description": [
                                        {
                                            "Realtor.COM Type": "Residential - Single Family"
                                        },
                                        {
                                            "Style": "Multi Level"
                                        },
                                        {
                                            "Basement": "No"
                                        },
                                        {
                                            "Stories": 2
                                        },
                                        {
                                            "Garage Type": "Att Garage"
                                        },
                                        {
                                            "Garage Stall": "3 or more"
                                        },
                                        {
                                            "SqFt B": 0
                                        },
                                        {
                                            "SqFt 1": 3585
                                        },
                                        {
                                            "SqFt 2": 1500
                                        },
                                        {
                                            "SqFt Source": "Assessor/Tax Roll"
                                        },
                                        {
                                            "New Construction": "No"
                                        },
                                        {
                                            "Lot Acres": 36.9
                                        },
                                        {
                                            "Lot Type 1": "Residential"
                                        },
                                        {
                                            "Lot Type 2": "Lake/River View"
                                        },
                                        {
                                            "Lake/River Name": "Granite Lake"
                                        }
                                    ]
                                }
                            ],
                            "Details": [
                                {
                                    "View": [
                                        {
                                            "Mountain": true
                                        },
                                        {
                                            "River": true
                                        }
                                    ]
                                },
                                {
                                    "Lot Features": [
                                        {
                                            "Irregular": true
                                        },
                                        {
                                            "Level": true
                                        }
                                    ]
                                }
                            ],
                            "Rooms": [
                                {
                                    "Id": "20110525151622697369000000",
                                    "ResourceUri": "/v1/listings/20101014195350951959000000/rooms/20110525151622697369000000",
                                    "Fields": [
                                        {
                                            "Room Name": "Bedroom"
                                        },
                                        {
                                            "Room Level": "1"
                                        },
                                        {
                                            "No. of Rooms": "2"
                                        },
                                        {
                                            "Area": "40"
                                        },
                                        {
                                            "Length": null
                                        },
                                        {
                                            "Width": null
                                        },
                                        {
                                            "Room Remarks": "Lorem ipsum dolor sit amet"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
                "DisplayCompliance":{
                    "IDXLogoSmall":{
                       "LogoUri":"http://somesite.com/logo/small.jpg",
                       "Type":"Uri"
                    },
                    "View":"Detail",
                    "IDXLogo":{
                       "LogoUri":"Acme Realty",
                       "Type":"Text"
                    }
                }   
            }   
        ],
        // Note that Pagination is returned only if the request includes _pagination=1
       "Pagination": {
            "TotalRows": 78,
            "PageSize": 25,
            "TotalPages": 4,
            "CurrentPage": 1
        }
    }
}
Restricted Fields
Fields that are not MlsVisible for a given listing's PropertyType will be masked (i.e. have a value of "********"). See the the Standard Fields service for more details.

My, Office, and Company Listings

URI: /<API Version>/my/listings

URI: /<API Version>/office/listings

URI: /<API Version>/company/listings

HTTP Method Description Notes
GET Retrieves listings listed by the current user, or under the current user's office or company. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:
Parameter Required Comments
Standard search and paging syntax No

GET Response

See the GET response section above for the data format.

Listings

URI: /<API Version>/listings/nearby

HTTP Method Description Notes
GET Retrieves listing data nearby a given coordinate
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

GET Response

See the GET response section below for the data format.

Response Format

For standard fields, Editability, visibility, searchability and list item labels will vary among users. Because of this, the settings for standard listing fields are discoverable using the Standard Fields service.

Not all listing data is suitable for display.
When using the Listings Service, you must consult the corresponding meta data services (e.g. Property Types and Standard Fields) for the PropertyType standard field and any other field where the HasList is true in the meta data.

See an example here.

Expansions

Expansion Roles Single Record Only? Selection Support? Description
CumulativeDaysOnMarket Private No No The cumulative number of days the listing has on been on market. Technically a Standard Fields, and is potentially searchable or disabled.
CustomFields All Yes No Custom fields are unstandardized listing data. As such, they will not be consistent among different MLSs. They are also not guaranteed to be static, so avoid writing software whose functionality depends on a particular custom field.

Cannot be used in conjunction with any other custom fields expansion. This expansions applies the MLS-defined human-readable labels to all custom fields and values, and thus cannot be used with the custom fields meta data.
CustomFieldsRaw All Yes No Nearly identical to the CustomFields expansions, with the exception that human-friendly labels are not applied to fields an values. Use this expansion in conjunction with the custom fields meta data.
CustomFieldsExpanded All Yes No All custom field data for the listing including data which is also displayed in StandardFields. Cannot be used in conjunction with any other custom fields expansion. This expansions applies the MLS-defined human-readable labels to all custom fields and values, and thus cannot be used with the custom fields meta data.
CustomFieldsExpandedRaw All Yes No Nearly identical to the CustomFieldsExpanded expansions, with the exception that human-friendly labels are not applied to fields an values. Use this expansion in conjunction with the custom fields meta data.
DaysOnMarket Private No No The number of days since the listing has been or was on market. Technically a Standard Fields, and is potentially searchable or disabled.
Documents All Yes Yes The list of documents attached to the listing.
ExpirationDate Private Yes No The date when the listing expires, which is a date value.
ListAgentPhoto All Yes No The listing agents photo if the listing agent information is available.
ListOfficePhoto All Yes No The listing offices photo if the listing office information is available.
OpenHouses All No Yes Upcoming open houses for the listing.
PortalCartNames Vow No No A list portal cart names the listing is in.
Photos All No Yes All photos for a listing. Cannot be used in conjunction with PrimaryPhoto
PrimaryPhoto All No No Returns only the primary photo for the listing. Cannot be used in conjunction with Photos
PrivateOfficeRemarks Private Yes No The private office remarks for the listing, which is a text value.
RentalCalendar All No No Upcoming dates through the next three months when the property will be unavailable for rental. Consult the Property Types service to see which property types support this expansion.
Rooms All Yes Yes Room data for the listing.
Supplement All Yes No Supplement data about the listing, which is a text value.
TourOfHomes Private No Yes Upcoming tour of home events for the listing.
Units All Yes Yes A list of units associated with the listing.
Videos All No Yes Videos for the listing.
VirtualTours All No Yes Virtual tours for the listing.

API Explorer

Interact with this service using the API Explorer.