Listings
This documentation has moved to the Spark Platform website. Please click here to view.
- Applicable API Key Roles
- Available Services
- Response Format
Applicable API Key Roles
This service is available to API keys with IDX roles. Within the IDX role, both IDX and Portal permissions may access this service. Listing data is restricted based on the API key and user’s current permission level. For example, IDX API keys will only have access to IDX listings. More information about roles may be found here.
Available Services
Retrieving full listing information
Listing services below generally are broken into two types: 1) searches run with specified criteria where zero or more listings are returned; and 2) a lookup on a specific listing ID that retrieves just that one listing, or no listing if the ID doesn’t match. The first type of service returns a set of listings. If a _limit parameter is supplied and it is set to a number greater than 1, then there are limits as to what fields are returned. For example, no custom fields are returned in this case. If the _limit parameter is set to 1 or if the second type of service is used, the developer may request that other fields excluded in the multi-result response be included via _expand, up to all available fields. This is useful for retrieving full listing information by list number, without first having to run a search followed by a request to an individual listing’s URI.
Search for Listings
URI: /<API Version>/listings/
| HTTP Method | Description | Notes |
|---|---|---|
| GET | Search for listings based on criteria and retrieve listing information for those listings. Listings and data will be filtered based on the API key’s permission level. | See parameters below |
| POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented |
GET Request
Parameters:
| Parameter | Required | Comments |
|---|---|---|
| Standard search parameters | No | If not specified, defaults to all listings that are visible with the current user’s permission. |
| Standard search and paging syntax | No | If not specified, defaults to the first page of listings and the default set of fields. |
| Hot sheet search parameters | No | The maximum date range that the /listings/ service supports is a 31 day span. If not specified, defaults to the last 24 hours. |
| Sub-resource search parameters | No | Example sub-resources include photos, open houses, etc. |
| Listing Response Field Selection | No | Any of the StandardFields attributes, such as PostalCode, BedsTotal, etc. may be specified in a comma-separated list. |
GET Response
This service returns data in the Listing Response Format.
Get an Individual Listing
URI: /<API Version>/listings/XX/
XX represents the listing ID as returned by any service that returns listing IDs (/listings/, for example).
| HTTP Method | Description | Notes |
|---|---|---|
| GET | Retrieve listing information for a single listing. The listing and its data will be filtered based on the current permission level. | See parameters below |
| POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented |
GET Request
Parameters:
- _expand : Optional. If supplied, must be one of the values on the sub-resource parameters page.
GET Response
This service returns data in the Listing Response Format.
Get My Listings
URI: /<API Version>/my/listings/
| HTTP Method | Description | Notes |
|---|---|---|
| GET | Retrieves listings listed by the current user. Using this service as a member will return just the member’s listings. Using this service as an office will return just the office’s listings. Likewise, for companies and the MLS. | See parameters below |
| POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented |
GET Request
Parameters:
- Accepts standard _filter parameters.
GET Response
This service returns data in the Listing Response Format.
Get Office Listings
URI: /<API Version>/office/listings/
| HTTP Method | Description | Notes |
|---|---|---|
| GET | Retrieves listings listed by the current user’s office. | See parameters below |
| POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented |
GET Request
Parameters:
- None.
GET Response
This service returns data in the Listing Response Format.
Get Company Listings
URI: /<API Version>/company/listings/
| HTTP Method | Description | Notes |
|---|---|---|
| GET | Retrieves listings listed by the current user’s company (a company is a collection of offices under the same ownership). If the user does not belong to a company, this service retrieves listings from the current user’s office. | See parameters below |
| POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented |
GET Request
Parameters:
- None.
GET Response
This service returns data in the Listing Response Format.
Listing Response Format
The response currently only delivers standard fields. Over time, more fields will become available in the standard fields section, and the non-searchable custom (non-standard) field section encapsulates the fields that aren’t available in standard format. Note that the fields in the custom fields section vary dramatically from MLS to MLS, so code accordingly.
Below is a sample response. Note that CustomFields may only be requested to be returned when an individual listing is queried by ID. Fields that have information that is not accessible at the current permission level will be returned with a series of asterisks instead of the actual data. For example, the PrivateRemarks field will typically be returned with a series of asterisks when accessing listing data using an IDX API key.
{
"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.flexmls.com/demomls/20080917142739989238000000-t.jpg",
"Uri300": "http://photos.com/demomls/20080917142739989238000000.jpg",
"Uri640": "http://resize.flexmls.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
"Uri800": "http://resize.flexmls.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
"Uri1024": "http://resize.flexmls.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
"Uri1280": "http://resize.flexmls.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
"UriLarge": "http://photos.flexmls.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.flexmls.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"
}
]
}
]
}
]
}
}
],
// Note that Pagination is returned only if the request includes _pagination=1
"Pagination": {
"TotalRows": 78,
"PageSize": 25,
"TotalPages": 4,
"CurrentPage": 1
}
}
}
Comments on this entry are closed.