Custom Location Extension 2

Layers and Filtering

All data is organized in the form of layers. When uploading, storing or search for information, a layer name string is specified and can be used to better filter relevant information.

Further filtering is possible by checking the geometry's attributes. These attributes are user-defined fields that are linked to a geometry, such as CLE2PointGeometry, and can be text or number fields.

Inserting and Uploading Data

To upload data to the CLE2 servers, you can use the web interface or REST APIs. Refer to the following User Guide for more details: https://developer.here.com/documentation .

It is also possible to insert data locally and to the server via SDK for Android. HERE SDK makes it straightforward to generate any location-referenced data even while storing it locally offline and sequentially sharing that information to other devices when a connection is established.

Performing Spatial Searches

To perform search, choose one of the search types as shown below. A common input parameter to all requests is the layer name.

Each of the search request types supports some common parameters as listed below.

Once you have a search request object created and set up according to your needs, call its execute(CLE2ResultListener) method. The result of the search will be delivered to the provided listener. You can get the geometries that matched search criteria from a CLE2Result object by calling getGeometries(). This list of geometry results may contain objects of the following types:

In the OpenGIS (the implementation standard for Geographic Information) and WKT representation formats the concept of a polygon is defined by one outer ring polygon plus zero or more inner hole polygons. This is the reason why CLE2PolygonGeometry class contains a GeoPolygon and a secondary GeoPolygon array.

Understanding Local and Full Search Results

While processing user-uploaded data CLE2 creates a look-up index where geometries are divided by an internal fixed grid. If a geometry spans across several grid tiles, then the search index may contain smaller slices of this uploaded geometry. This behavior allows for better search performance as well as optimized return values, since it is possible to only return the relevant part of the originally submitted geometry, and thus reducing the response size and processing time.

Before executing a search you can specify if you are only interested in the part of the geometry that falls within the tiles around the search area (in other words, the tiled "local" geometry), or if you would like to receive the full geometry as originally uploaded.

Figure 1. Local and Full Geometry

You can use the following three options to define whether you are requesting for full or local results. These options are available for all search types:

Proximity Search Request Example

To perform a custom location search, you need to create a CLE2ProximityRequest using the CLE2ProximityRequest(String layerId, GeoCoordinate center, int radius) or CLE2ProximityRequest(List<String> layerIds, GeoCoordinate center, int radius) constructor methods.

A proximity search returns a list of custom locations that fall within a specified radius of a GeoCoordinate location. For example, the following code shows how to perform a search for all locations in the previously-mentioned stores layer that exists within an 8 kilometer radius of Frankfurt Central Station:

String layerId = "HERE_SITES";
int radius = 8000; // 8 km
GeoCoordinate location = new GeoCoordinate(49.196261, -123.004773);
CLE2ProximityRequest req = new CLE2ProximityRequest(layerId, location, radius);
req.execute(new CLE2Request.CLE2ResultListener() {
  @Override
  public void onCompleted(CLE2Result result, String error)
  {
    // if CLE2Error.NONE.equals(error) is true, the request was successful
    if (error.equals(CLE2Error.NONE)) {
      List<CLE2Geometry> gemetry = result.getGeometries();
      for (CLE2Geometry geo : gemetry) {
        java.util.Map<String, String> attributeMap = geo.getAttributes();
        String name = attributeMap.get("NAME1");
        double distance = geo.getDistance();
      }
    }
  }
});

The layerId parameter represents a set of custom locations. For example, layerID="HERE_SITES" represents an example layer that contains HERE locations in Germany. You can also perform a proximity search on different layers at the same time:

List<String> layerIds = new ArrayList<String>();
layerIds.add("LAYER_1");
layerIds.add("LAYER_2");
int radius = 500; // 500 meters
GeoCoordinate location = new GeoCoordinate(50.113905,8.677608);
CLE2ProximityRequest req = new CLE2ProximityRequest(layerIds, location, radius);
req.execute(new CLE2Request.CLE2ResultListener() {
  @Override
  public void onCompleted(CLE2Result result, String error)
  {
    // if CLE2Error.NONE.equals(error) is true, the request was successful
    if (error.equals(CLE2Error.NONE)) {
      List<CLE2Geometry> gemetry = result.getGeometries();
      for (CLE2Geometry geo : gemetry) {
        java.util.Map<String, String> attributeMap = geo.getAttributes();
        String name = attributeMap.get("NAME1");
        double distance = geo.getDistance();
      }
    }
  }
});

After creating a request object you can call execute(ResultListener) method to launch the search request and listen for search results.

You can also add a filter to the request. A filter is a JavaScript-like expression that is evaluated for each location-matching search query. When specified, only locations where the expression evaluates to true are returned. For example, if you want to filter for location results that have the custom location parameter of rating greater than 3 and the name "MyPlace23", perform the following:

String layerId = "HERE_SITES";
int radius = 8000; // 8 km
GeoCoordinate location = new GeoCoordinate(49.196261, -123.004773);
CLE2ProximityRequest req = new CLE2ProximityRequest(layerId, location, radius);
String filter = "CITY == 'Burnaby' && NAME1 != 'MyPlace'";
req.setQuery(filter);
req.execute(new CLE2Request.CLE2ResultListener() {
  @Override
  public void onCompleted(CLE2Result result, String error)
  {
    // if CLE2Error.NONE.equals(error) is true, the request was successful
    if (error.equals(CLE2Error.NONE)) {
      List<CLE2Geometry> gemetry = result.getGeometries();
      for (CLE2Geometry geo : gemetry) {
        java.util.Map<String, String> attributeMap = geo.getAttributes();
        String name = attributeMap.get("NAME1");
        double distance = geo.getDistance();
      }
    }
  }
});

Iterating Over Results

The CLE2Result object contains a list of geometries that are the result of the search and makes them available with getGeometries() method. Since different types of geometry can be returned, it is recommended to test for the type before using it. For example, you can use CLE2ResultListener in a similar manner as in the following example:

CLE2ResultListener resultListener = new CLE2Request.CLE2ResultListener() {
  @Override
  public void onCompleted(CLE2Result result, String error) {
    if (!error.equals(CLE2Request.CLE2Error.NONE)) {
      // process search results
      for (CLE2Geometry geometry : result.getGeometries()) {
        if (geometry instanceof CLE2PointGeometry) {
          CLE2PointGeometry point = (CLE2PointGeometry) geometry;
          // work with point geometry data
        }
      }
    } else {
      // handle error
    }
  }
};