The ListAssist HomeSearch API allows natural language text searches to be matched to property listings.
\nTo start using the HomeSearch API, you need
\nA valid API Key - we provide these directly after consultation with our team.
\nConfirmation of your required real estate data access
\nAccess has been agreed in-line with our data integration procedures OR
\nRequired data coverage has been confirmed with our team, provided from our aggregated feed
\nThe HomeSearch API uses API keys for authentication.
\nThe API key must be passed to the ListAssist API in the X-Api-Key request header.
If an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.
\nAll responses are returned in the form
\n{ \n \"metadata\": [],\n \"errors\": [],\n \"results\": []\n}\n\nThe /search endpoint receives a text search and returns a list of property results and their match scores. The response also includes data our model has extracted. These extracted fields can be used to populate dropdown filters; inform internal analytics; and build customer profile information if desired.
text - a natural language search. Text must be between 5 - 300 characters in length or a 400 response will be returned with an error message stating the search text is invalid.
location_bias - a polygon defined by two points in the following format: rectangle:lat,lon|lat,lon. The two points required are the South West and North East corners - bottom left and top right when viewing a map. This value is used to help resolve locations that may have common names*
*our location resolution involves several steps. See the Location section below for a full overview.
\nNote: Coordinates are bounded -180 to 180 latitude, -90 to 90 longitude. Some map components will return unbounded values.
\nLocation polygons are currently limited to simple rectangles with edges running North-South and East-West. This means that some resolved polygons may not tightly fit a given location, causing results to appear outside the expected area.
\nThe diagonal length of the location polygon cannot exceed a Haversine distance of 2000 kilometers (~1242 miles). If a polygon is larger than this bound it will generate a 400 response with an error message stating the search area is too large.
\nmax_results - total number of search results to return. Values between 1 - 100 are valid. If a value less than 0 or greater than 100 is passed, 10 results will be returned.
page_index - the index of the desired page of results, starting at index 1. When not passed, the default value is 1.
session_id - UUID, unique identifier for a frontend user or contiguous user session. If given, allows definitive tracking of user behaviour.
features - allows override values for some numeric values to be passed. This allows for hybrid search functionality where dropdown inputs or other UI components have their settings passed in complement to the natural language search. The override fields will always be used, even if the natural language search contains values outside of the override range.
The following is a list of all override fields:
\nmin_price (integer) - minimum listing price
max_price (integer) - maximum listing price
min_bedrooms (integer) - minimum bedrooms
max_bedrooms (integer) - maximum bedrooms
min_bathrooms (float) - minimum bathrooms
max_bathrooms (float) - maximum bathrooms
min_year_built (integer) - minimum build year
max_year_built (integer) - maximum build year
min_building_sqft (integer) - minimum internal building area
max_building_sqft (integer) - maximum internal building area
min_lotsize_acres (float) - minimum lotsize
max_lotsize_acres (float) - maximum lotsize
location (string) - a location that will be used to bias search results, e.g \"New York\"
Any combination of these fields is supported. Passing only a min or max value will work, the other end of the range will remain unbounded unless a user's search defines a bound. We strongly recommend passing both min and max values to prevent any odd behaviour with users input.
For example, a user enters \"5 bedroom house\", and the override values contain max_bedrooms: 4. The user input sets the search range to min_bedrooms: 5, max_bedrooms: 5. The override value of 4 is then applied, leading to a search range of min_bedrooms: 5, max_bedrooms: 4. This will return no results.
To access paged results, pass the page_index field with the desired page index. Values greater than 1 use the max_results field as to indicate the number of items to skip. For example, given the following values
{\n ...,\n \"max_results\": 50,\n \"page_index\": 5\n}\n\nThe first 200 results will be skipped, and items ranked 201-250 will be returned.
\nContextual information about the current page can be view in the metadata field of a response body.
Note: only the first 3000 results are available, even with pagination.
\nOur location resolution tries to resolve a search area with the following hierarchy
\nUser input - locations parsed from a search text, biased using any passed location_bias polygon
The location_bias polygon value. When no location is given by a user, the location_bias becomes the search area.
A default client location polygon. This is a default value provided to ListAssist that serves as a fallback when no value is passed.
\nThe API supports multi-location resolution from text input. For example, if the following search text is passed
\n3 bed condo in Brooklyn or Hoboken
then both Brooklyn and Hoboken suburb polygons will be resolved and used for the property search.
\nIf a text input is an exact address, for example
\n123 Main Street, Brooklyn, New York
then a stricter polygon with a 150 meter (~490 ft) diagonal be used during the search.
\nA successful search will return an array of properties in the results field, in the form
{\n \"fk_id\": \"string\",\n \"mls_number\": \"string\",\n \"lat\": float,\n \"lon\": float,\n \"score\": float\n}\n\nNote: Legacy fields may be visible, we do not guarantee presence of these fields. They may be removed without warning.
\nfk_id - the unique ID for a listing in the form UOID:ListingId or MLS Source name:ListingId
mls_number - the unique ID assigned to a property by the MLS, AOR, or other real estate data provider that the property originated from. Used as the second half of fk_id - the ListingId
lat - latitude of the property
lon - longitude of the property
score - the match score generated by ListAssist. Minimum 0, maximum 1.
fk_id uses the RESO certification ID when you use ListAssist's aggregated feed.
If you provide your data to us via file or API then the key will instead use the MLS source name (RESO - OriginatingSystemName).
\nThe request was executed correctly, but the user's input generated an error.
\nThe results and metadata fields will be null, the errors field will have a user friendly string in its array.
{\n \"metadata\": null,\n \"errors\": [\"The input text was marked as invalid. Please try again.\"],\n \"results\": null\n}\n\nThe request failed to complete due to a client error, such as
\nincorrect API key
\nsearch area polygon was too large
\nmalformed request
\n{\n \"metadata\": null,\n \"errors\": [\"Invalid API key.\"],\n \"results\": null\n}\n\nThe request failed to complete due to an error on our end, such as
\n{\n \"metadata\": null,\n \"errors\": [\"Our systems are currently experiencing high load. Please try again.\"],\n \"results\": null\n}\n\n