Skip to main content

Search Results API

This API endpoint is used to retrieve search results for a specific saved search embed. The API returns a JSON response containing a list of listings that match the search criteria. This API is commonly used by web developers to dynamically display property listings on a website.

API Endpoint​

The endpoint URL is structured as follows:

https://[your-site-name].peakidxsites.com/search-results-api/[search-embed-id]?apikey=[your-api-key]

Replace your-site-name with the name of your PeakIDX site and search-embed-id with the unique ID of the saved search embed from the Search Embeds page.

Request Parameters​

This API can be used client-side (in-browser) or server-side.

Client-side Usage​

When using the API client-side, the request must not contains the API Key. Instead, the request must include the Origin headers to validate the request's source.:

  • Origin: The domain of the website making the request. This must match the domain configured in the PeakIDX site's Site Settings.

Server-side Usage​

  • apikey: The API requires a valid API key for authentication. You can obtain an API key for your site by going to the Sites Page and clicking the Admin dropdown menu (represented by a gear icon) for your site, then selecting API Key.

Optional Query Parameters​

  • offset: An optional integer specifying the starting position for the results. The value must be between 0 and 10000. The default is -1 which returns the first page.

  • limit: An optional integer specifying the maximum number of results to return. The value must be between 0 and 200. The default is 10.

  • offset: An optional integer specifying the starting position for the results. The value must be between 0 and 10000. The default is -1 which returns the first page.

  • limit: An optional integer specifying the maximum number of results to return. The value must be between 0 and 200. The default is 10.

Response​

The API returns a JSON object.

Success Response​

On a successful request, the API returns a JSON object containing the search results. An example is shown below:

{
  "total": 100,
  "count": 10,
  "listings": [
    {
      "listingId": 123456,
      "address": "123 Main St",
      "city": "Anytown",
      "price": 250000,
      "beds": 3,
      "baths": 2.5
    },
    ...
  ]
}
  • total: The total number of listings found that match the search criteria.
  • count: The number of listings returned in the current request. This will be equal to or less than the limit.
  • listings: An array of listing objects, each containing details about a property.

Error Handling​

The API will return a plain text error message under the following conditions:

  • Invalid api key, referer or origin.: This error occurs if the provided apikey is incorrect, or if the request's origin and referer headers do not match the configured website settings.
  • Invalid search embed id.: This error indicates that the searchEmbedId provided in the URL does not correspond to a valid saved search embed.
  • Invalid offset: This error occurs if the offset parameter is outside the valid range (0 to 10000).
  • Invalid limit: This error occurs if the limit parameter is outside the valid range (0 to 200).
  • Invalid search criteria.: This error indicates an issue with the saved search criteria associated with the searchEmbedId.