Custom Location Extension 2

Layers and Filtering

All data is organized in the form of layers. When uploading, storing, or searching 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 attributes. These attributes are user-defined fields that are linked to a geometry, such as NMACLE2GeometryPoint, and can be text or number fields.

Inserting and Uploading Data

To upload CLE2 data, 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 iOS. HERE SDK makes it straightforward to generate any location-referenced data even when storing it locally offline and sequentially sharing that information to other devices when a connection is established.

Performing Spatial Searches

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

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

Once you have a search request object created and set up according to your needs, call its startWithListener: or startWithBlock: methods. The result of the search will be delivered to the provided block or 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 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 the class NMACLE2GeometryPolygon contains an NMAGeoPolygon and a secondary NMAGeoPolygon 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 reduce the response size and processing time.

Before executing a search you can specify if you are only interested in 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:

You can set the geometry type by using setGeometryType: method:

NMACLE2ProximityRequest *proximityRequest =
  [[NMACLE2ProximityRequest alloc] initWithLayer:searchLayer center:coordinates radius:radius];
[proximityRequest setGeometryType:NMACLE2GeometryFull];
      

Proximity Search Request Example

To perform a custom location search, you need to create an NMACLE2ProximityRequest using initWithLayer:center:radius or initWithLayers:center:radius methods.

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

NMACLE2ProximityRequest * proximityRequest;
proximityRequest= [[NMACLE2ProximityRequest alloc] initWithLayer:@"HERE_SITES"
       center:[NMAGeoCoordinates geoCoordinatesWithLatitude:49.196261
          longitude:-123.004773]
       radius:8000]; // 8km

// Perform the request
[proximityRequest startWithBlock:^(NMACLE2Request *request, NMACLE2Result * result, NSError *error) {
    if(!error) {
      // use result.geometriesArray to retrieve list of found NMACLE2Geometry results
    }
  }];

The Layer ID parameter represents a set of custom uploaded geometries. For example, "HERE_SITES" layer ID represents a sample layer that contains locations of HERE offices in Germany. Since offices are represented by simple points, the returned geometries are of type NMACLE2GeometryPoint.

You can also perform proximity search on different layers at the same time:

NSArray *layers = @[@"LAYER_1", @"LAYER_2"];
NMACLE2ProximityRequest * proximityRequest;
proximityRequest= [[NMACLE2ProximityRequest alloc] initWithLayers:layers
       center:[NMAGeoCoordinates geoCoordinatesWithLatitude:50.113905
              longitude:8.677608]
       radius:500]; // 500 meters

// Perform the request
[proximityRequest startWithBlock:^(NMACLE2Request *request, NMACLE2Result * result, NSError *error) {
    if(!error) {
      // use result.geometriesArray to retrieve list of found NMACLE2Geometry results
    }
  }];

After creating a request object you can call startWithBlock: 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 geometries for which the expression evaluates to true, e.g. when attributes are matching, are returned. For example, if you want to find geometries that have the custom location parameter of rating that is greater than 3 and the attribute "NAME" as "MyPlace23", perform the following:

NMACLE2ProximityRequest * proximityRequest;
proximityRequest= [[NMACLE2ProximityRequest alloc] initWithLayer:@"HERE_SITES"
       center:[NMAGeoCoordinates geoCoordinatesWithLatitude:49.196261
              longitude:-123.004773]
       radius:8000]; // 8 km

[proximityRequest setQuery:@"CITY == 'Burnaby' && NAME1 != 'MyPlace'"];

// Perform the request
[proximityRequest startWithBlock:^(NMACLE2Request *request, NMACLE2Result * result, NSError *error) {
    if(!error) {
      // use result.geometriesArray to retrieve list of found NMACLE2Geometry results
    }
  }];

Iterating Through Results

The NMACLE2Result object contains an NSArray with all the NMACLE2Geometry objects found. Since different objects can be returned, it is recommended to test for type before using the returned geometry. For example, you can perform the following inside the request completion block:

for (NMACLE2Geometry *currentLocation in result.geometries) {
  if([currentLocation isKindOfClass:[NMACLE2GeometryMultiPoint class])
  {
    NMACLE2GeometryMultiPoint *multiPoint = (NMACLE2GeometryMultiPoint *)currentLocation;
    // multiPoint.coordinatesArray is an NSArray containing the found NMAGeoCoordinates
    NSLog(@"Found %lu coordinates", (unsigned long)[multiPoint.coordinatesArray count]);
    NSLog(@"Geometry attributes: %@", multiPoint.attributes);
  }
}

Each found NMACLE2GeometryMultiPoint contains two important properties: a coordinates NSArray and an attributes NSDictionary with flexible user-defined fields.