Skip to content

GeoPoint Clustering

Geo point search in a category, radius or a rectangular area may return too many geo points within close geographic proximity from each other. This might be difficult to view and process in a client application. To address this problem, Backendless supports the * geo clustering* feature. A geo cluster is a group of several geo points located close to each other. The two screenshots below demonstrate the advantages of clustering: the picture on the top displays search results in the Backendless Console with clustering turned off and the one on the bottom displays search results as clusters when clustering has been enabled:

Geo Points View:

clustering-points.zoom50

Clusters and Points View:

clustering-clusters.zoom50

Backendless creates clusters by splitting the map into a grid of squares. Geo points which belong to a square are placed into the same cluster. When a square contains only one point, it remains non-clustered.

Testing Geo Clustering in Backendless Console

The Geolocation page displays non-clustered geo points by default. To see how geoclustering works and test geoclustering search results:

  1. Log in to Backendless Console, select an application and click the Geolocation icon.
  2. Click the Map-driven navigation toggle. The toggle changes how the geo points are loaded from the backend. In the map-driven mode console loads the geo points for the visible area of the map.
  3. Click the Geo Clustering toggle to enable clustering.
  4. Console reloads geo points and clusters for the current viewport of the map and displays the results. A cluster is visualized as a blue marker on the map with a number indicating how many geo points it represents.
    geofence-screen7.zoom50

Geo clustering is also available with the "Search in Radius" option, which searches for geo points in a circular area. To enable this functionality, click the Search in radius toggle:

geofence-screen8.zoom50

If you want to see the geo points in a cluster, zoom in the map or double-click a cluster's marker. Zooming the map in too much (when using the clustering along with the search in radius) may result that the search radius will be much bigger than the visible part of the map on the screen. In this case, zoom out so you can adjust the circle position and/or radius.

Clicking a cluster's marker will reveal the coordinates and combined metadata of all geopoints in the cluster.

geofence-screen9.zoom50

Retrieving Clustered Geo Points

The API calls for searching the geo points may return clusters if the following parameters are present in the request:

  1. dpp - degree per pixel. Use the following psuedo algorithm to calculate the value of dpp:
if (eastLongitude - westLongitude) < 0  

  dpp = ((eastLongitude - westLongitude) + 360) / mapWidth  

else  

  dpp = ((eastLongitude - westLongitude) / mapWidth

where:

  • westLongitude - the longitude of any point on the western boundary of the map in degrees.
  • eastLongitude - the longitude of any point on the eastern boundary of the map in degrees. | Argument                | Description | | --- | --- | | mapWidth | the size of the viewing area of the map in pixels. |

  • clusterGridSize - the size in pixels of the grid's squares used to group points into clusters. The default value is 100 pixels.

These parameters can be added to any request which returns a collection of geo points, including retrieval of geo points from a category, radius or rectangular area search.

Sample Request:

curl -X GET \  
-v "https://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/points?categories=Restaurants,Cafe&dpp=0.01&clusterGridSize=45"

Sample Response Body

The sample response below demonstrates one cluster containing nine geo points and one separate (not included into the cluster) geo point.

[  
  {  
    "objectId":"1",  
    "categories":["Restaurants","Caffee"],  
    "metadata":{},  
    "latitude":30,  
    "longitude":40,  
    "totalPoints":9,  
  },  
  {  
    "objectId":"XXXX-XXXX-XXXX-XXXX",  
    "categories":["Restaurants"],  
    "metadata":{},  
    "latitude":45,  
    "longitude":30  
  }  
]

Notice the totalPoints property in the first object in the array. The presence of that property defines the object as a geo cluster. The value of the property is how many geo points the cluster contains. Other than that, all other properties are identical to geo points. If the totalPoints property is not present, it means the geo point was returned non-clustered. This occurs when a geo point does not have any other neighboring points within the same grid's square.


Loading Geo Points from a Cluster

With the geo clustering feature enabled, you may need to reveal the geo points gathered in a cluster. In the Backendless Console, you can click the cluster to reveal its details as described above. By using the calls described below, you will be able to reveal the geo points in a cluster via API.

Method

GET

URL

https://api.backendless.com/<application-id>/<REST-api-key>/geo/clusters/<clusterId>/points?lat=x.xxxx&lon=y.yyyy&units=UNITSVALUE&categories=ABC,XYZ&r=ZZ[&nwlat=X.XXXX&nwlon=YY.YYYY&selat=ZZ.ZZZZ&selon=WW.WWWW][&metadata={"AAAA":"foo", "BBBB":"bar"}]&dpp=YY.YY&size=XX[&pagesize=XX][&offset=XX]

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
lat the latitude of a cluster.
lon the longitude of a cluster.
  • - ID of a cluster assigned by Backendless. | Argument                | Description | | --- | --- | | <units> | unit of measure applied to the radius value. Supported unit values are: METERS, KILOMETERS, MILES, YARDS, FEET | | categories | categories' names of the geo points belonging to a cluster. | | <radius> | distance from the center point, within which to run the search. | | <metadata> | metadata which must match in order for a point to be selected for the search result. Must be expressed in as a URL encoded JSON object. For example, { "foo":"bar" } will be URL encoded as:  %20%7B%20%22foo%22%3A%22bar%22%20%7D. Found geo points must match the specified metadata key/value pairs entirely. Accepted values for this parameter are: String, Number (integer and double), and property names of the related objects stored in the database. Date values must be represented as number in the Unix timestamp format (number of milliseconds since January 1, 1970 at UTC). Learn more about using date in search queries for category, radius, or rectangular area search. | | dpp | degrees per pixel parameter of a cluster. Learn more about this parameter. | | <pageSize> | number of geo points to be returned in the response. | | <metaInResponse> | Boolean value indicating whether geo point metadata should be included in the response. Supported values are true or false. | | <offset> | sequential (zero-based) index from where to run the search. For example, suppose the first search query returned 50 geo points (pageSize is set to 50). A subsequent search should set the offset value to 50 in order to get the next page of search results. |

Request Body

none

Response Body

A JSON array of geo points, identical to response for the Search in Category request.