Map Clustering Implementation Guide
Our real estate APIs feature a map clustering capability that optimizes the display of listings on a map. This feature significantly improves performance by clustering listings server-side, thereby reducing the need to handle large datasets on the front-end.
To request clusters of listings, set the cluster parameter to true in your API request:
GET https://api.repliers.io/listings?cluster=true
For a map-only experience, it's recommended to set listings to false to improve load times. This ensures that only cluster data is returned without the detailed listing data:
GET https://api.repliers.io/listings?cluster=true&listings=false
The clusterPrecision parameter controls the density of clusters:
Lower precision values result in fewer clusters with more listings per cluster.
Higher precision values result in more clusters with fewer listings per cluster.
The value ranges from 1 to 29. Adjust the clusterPrecision based on the map zoom level for optimal results. For example, many users set clusterPrecision to match the zoom value provided by mapping libraries like Google Maps or Mapbox.
Here’s an example that sets clusterPrecision to 10 and requests specific fields for clusters containing a single listing:
GET https://api.repliers.io/listings?cluster=true&clusterFields=mlsNumber,listPrice,address.city&listings=false&clusterPrecision=10
The clusterLimit parameter allows you to limit the number of clusters returned in the response. This value can range from 1 to 200.
GET https://api.repliers.io/listings?cluster=true&clusterLimit=100
When a cluster contains a single listing, the cluster includes additional fields for that listing. This is useful for displaying details like listPrice in map applications. You can specify which fields to return using the clusterFields parameter.
GET https://api.repliers.io/listings?cluster=true&clusterFields=mlsNumber,listPrice,address.city&listings=false&clusterPrecision=10
In this request we specify that for clusters containing a single listing we'd like to have the mlsNumber, listPrice and city values.
To include statistics in your clusters, set clusterStatistics to true and use the statistics parameter. This feature is ideal for creating heat maps that compare different geographies based on market data.
GET https://api.repliers.io/listings?cluster=true&statistics=avg-listPrice&clusterStatistics=true
In this request we specify that we'd like to see the average listPrice statistic for all listings within each cluster
Our map clustering feature provides an efficient way to display large datasets on a map by aggregating listings server-side. Adjusting parameters like clusterPrecision, clusterFields, and clusterStatistics allows you to tailor the clustering to your specific needs, ensuring a smooth and responsive user experience.
Requesting Clusters
To request clusters of listings, set the cluster parameter to true in your API request:
GET https://api.repliers.io/listings?cluster=true
Example Response Containing Clusters
{
"aggregates": {
"map": {
"clusters": [
{
"count": 19585,
"location": {
"latitude": 43.70534443195513,
"longitude": -79.36733720479269
},
"bounds": {
"bottom_right": {
"latitude": 43.633363377302885,
"longitude": -79.10189635120332
},
"top_left": {
"latitude": 43.83431699126959,
"longitude": -79.45311376824975
}
},
"map": [
[
[
-79.45311376824975,
43.83431699126959
],
[
-79.45311376824975,
43.633363377302885
],
[
-79.10189635120332,
43.633363377302885
],
[
-79.10189635120332,
43.83431699126959
],
[
-79.45311376824975,
43.83431699126959
]
]
]
},
{
"count": 11050,
"location": {
"latitude": 43.683894202150654,
"longitude": -79.59600708914154
},
"bounds": {
"bottom_right": {
"latitude": 43.58039586804807,
"longitude": -79.45316883735359
},
"top_left": {
"latitude": 43.83450788911432,
"longitude": -79.8046560678631
}
},
"map": [
[
[
-79.8046560678631,
43.83450788911432
],
[
-79.8046560678631,
43.58039586804807
],
[
-79.45316883735359,
43.58039586804807
],
[
-79.45316883735359,
43.83450788911432
],
[
-79.8046560678631,
43.83450788911432
]
]
]
}
]
}
}
}Map-Only Experience
For a map-only experience, it's recommended to set listings to false to improve load times. This ensures that only cluster data is returned without the detailed listing data:
GET https://api.repliers.io/listings?cluster=true&listings=false
Cluster Precision
The clusterPrecision parameter controls the density of clusters:
Lower precision values result in fewer clusters with more listings per cluster.
Higher precision values result in more clusters with fewer listings per cluster.
The value ranges from 1 to 29. Adjust the clusterPrecision based on the map zoom level for optimal results. For example, many users set clusterPrecision to match the zoom value provided by mapping libraries like Google Maps or Mapbox.
Example Request
Here’s an example that sets clusterPrecision to 10 and requests specific fields for clusters containing a single listing:
GET https://api.repliers.io/listings?cluster=true&clusterFields=mlsNumber,listPrice,address.city&listings=false&clusterPrecision=10
Cluster Limit
The clusterLimit parameter allows you to limit the number of clusters returned in the response. This value can range from 1 to 200.
GET https://api.repliers.io/listings?cluster=true&clusterLimit=100
Single Listing Clusters & the clusterFields Parameter
When a cluster contains a single listing, the cluster includes additional fields for that listing. This is useful for displaying details like listPrice in map applications. You can specify which fields to return using the clusterFields parameter.
Example Request for Single Listing Clusters
GET https://api.repliers.io/listings?cluster=true&clusterFields=mlsNumber,listPrice,address.city&listings=false&clusterPrecision=10
In this request we specify that for clusters containing a single listing we'd like to have the mlsNumber, listPrice and city values.
Example Cluster Containing A Single Listing & Listing Fields
{
"count": 1,
"location": {
"latitude": 43.81639128550887,
"longitude": -79.60495973937213
},
"bounds": {
"bottom_right": {
"latitude": 43.81639128550887,
"longitude": -79.60495973937213
},
"top_left": {
"latitude": 43.81639128550887,
"longitude": -79.60495973937213
}
},
"map": [
[
[
-79.60495973937213,
43.81639128550887
],
[
-79.60495973937213,
43.81639128550887
],
[
-79.60495973937213,
43.81639128550887
],
[
-79.60495973937213,
43.81639128550887
],
[
-79.60495973937213,
43.81639128550887
]
]
],
"listing": {
"mlsNumber": "N8372244",
"listPrice": "4500.00",
"address": {
"city": "New York"
}
}
}Cluster Statistics
To include statistics in your clusters, set clusterStatistics to true and use the statistics parameter. This feature is ideal for creating heat maps that compare different geographies based on market data.
Example Request for Cluster Statistics
GET https://api.repliers.io/listings?cluster=true&statistics=avg-listPrice&clusterStatistics=true
In this request we specify that we'd like to see the average listPrice statistic for all listings within each cluster
Example Of Cluster Containing Statistics
{
"count": 3,
"location": {
"latitude": 43.82331159431487,
"longitude": -79.60820881649852
},
"bounds": {
"bottom_right": {
"latitude": 43.82331159431487,
"longitude": -79.60820881649852
},
"top_left": {
"latitude": 43.82331159431487,
"longitude": -79.60820881649852
}
},
"map": [
[
[
-79.60820881649852,
43.82331159431487
],
[
-79.60820881649852,
43.82331159431487
],
[
-79.60820881649852,
43.82331159431487
],
[
-79.60820881649852,
43.82331159431487
],
[
-79.60820881649852,
43.82331159431487
]
]
],
"statistics": {
"listPrice": {
"avg": 300533
}
}
}Conclusion
Our map clustering feature provides an efficient way to display large datasets on a map by aggregating listings server-side. Adjusting parameters like clusterPrecision, clusterFields, and clusterStatistics allows you to tailor the clustering to your specific needs, ensuring a smooth and responsive user experience.
Updated on: 04/07/2024
Thank you!