Property Search API endpoint can potentially return thousands of matched properties. To avoid extraneous network load, this endpoint limits the number of records returned in the response and charges only for properties that are retrieved using the skip and take request parameters, rather than the total number of properties matched.
This guide illustrates how to request paginated data and access each page of results.
How it works
Property search API end-point, by default, limits the number of records returned in the response. In order to retrieve a large number of properties, the skip and take request parameters are used to implement paging
Parameters
skip: bypasses a specified number of search results, then return the remaining results. Default value is 0
take: specifies the number of search results to return. Default value is 25.
sessionId: sessionId is required when making pagination requests. The session ID request option ensures that API pagination using the skip & take request options will return the correct search results across pagination requests. Session ID can be any valid string. The same value used in the initial API request should be used for all subsequent pagination requests. A new session Id should be used when initiating a new API request.
Make a paginated request and iterate through the pages
You can set the number of results to return per page using the take parameter. If you don't specify a take parameter, then the endpoint will use its default page limit i.e. 25 results per page. You can also set other parameters in this request to narrow down your results.
The following example request asks the property search endpoint for all properties that belong to AZ state, with a take of 25 properties per page of results
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 0,
"take": 25,
"sessionId": "examplesessionid001"
}
}
Since only 25 properties are returned at a time in your response, you can get the rest of the items in batches using the skip parameter in subsequent requests.
{
"searchCriteria": { "query": "Phoenix, AZ"
},
"options": {
"skip": 25,
"take": 50,
"sessionId": "examplesessionid001"
}
}
💡 Use the resultsFound parameter in result.meta object to check the total count of the matched properties for the given request.
Change the number of results for a specific page
Use the take parameter to change that value up to a maximum of 1000. However, we recommend to request not more than 500 results in a single API call as that can result into 502 Bad Gateway error due to memory overload while processing large amount of data.
For example, following requests asks property search endpoint for all properties that belong to AZ state, to return 500 results
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 0,
"take": 500,
"sessionId": "examplesessionid001"
}
}
If the take value exceeds 1000, an exception is thrown.
{
"status": {
"code": 400,
"text": "Bad Request",
"message": "Invalid request. Take option should not be greater than
1000"
}
}