Custom Location Extension 2
Custom Location Extension 2 (CLE2) allows you to easily distribute custom geospatial information in your mobile applications. Through CLE2 you can programatically insert spatial content to the local database and upload it to the server for data sharing purposes. You can also also perform online or offline searches. These features effectively turns SDK for iOS into a lightweight spatial storage solution that enables insertion and query for geospatial information using optimized algorithms.
The classes that support this feature are located under NMA Custom Location Extension 2 group. Instead of having specific interfaces for location and geometry requests CLE2 unifies all use cases in one flexible approach: the returned value always contains one of the geometry types (such as NMACLE2GeometryPoint
), along with a set of 0 to N user-defined attributes that can represent any information. There is no implied structure in these attributes. These attributes are made available as a map of key and attribute values.
Some examples of how you can use these CLE2 features include:
- Show all users' custom Points of Interest (POIs) within a 2km radius.
- Online or offline search for all customer offices within Germany using an area defined by a polygon, then display the offices' reception phone numbers, employee counts, and other details.
- Edit geometry shapes in real time in offline mode and perform queries against them to get notifications when such shapes intersect with other existing fixed shapes and other basic Geofencing solutions. For example, this can be a ‘moving platform’, e.g. ships near ship docks, where locations are relative to GPS movements.
- Sharing Points of Interest that are not officially available as part of HERE map data, such as city facilities and outdoor basketball courts.
- Persist GPS data that is tied to arbitrary data, e.g. hiking trails with speed, even during offline mode.
- Search for specific types of objects that are near a given route.
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.
Search Type | Description | Class Name |
---|---|---|
Proximity | Retrieve geometries that are within a given radius from a center. | NMACLE2ProximityRequest |
Corridor | Retrieve geometries along a route specified by a sequence of coordinates. | NMACLE2CorridorRequest |
Bounding box | Retrieve geometries within a specified rectangular geographic area. | NMACLE2BoundingBoxRequest |
Quadkey | Retrieve geometries that fall within a specified QuadKey. | NMACLE2QuadkeyRequest |
Attribute | Retrieve all geometries that match with a specified query. This type of search is only available online. | NMACLE2AttributeRequest |
Each of the search request types supports some common properties as listed below.
Property | Description | Example Values |
---|---|---|
geometryType | Specifies geometry type to be given in the result (online only), see details below on "Understanding the search results". |
|
cachingEnabled | Default is False. If enabled, geometries received from such online search request will be stored locally. | |
query | Currently available for online requests only, this property allows a query filter to be specified on the user's geometry attributes so that only geometries that pass the filter were returned. Accepted strings are free form text with simple equality and comparison operators. |
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:
Class | Geometry Description | Main Properties |
---|---|---|
NMACLE2Geometry | Base class for all other geometry return values containing user-defined attributes. | NSDictionary<NSString *, NSString *> *attributes |
NMACLE2GeometryPoint | Represents a point in coordinates. Relates to a Point in WKT. | NMAGeoCoordinates *coordinates |
NMACLE2GeometryMultiPoint | Represents a multi-point as a coordinates array. Relates to a MultiPoint in WKT. | NSArray<NMAGeoCoordinates *> *coordinatesArray |
NMACLE2GeometryPolyline | Represents a polyline as an NMAGeoPolyline . Relates to a WKT LineString object. | NMAGeoPolyline *geoPolyline |
NMACLE2GeometryMultiPolyline | Represents a multi-polyline as an array of NMAGeoPolyline . Relates to a WKT MultiLineString object. | NSArray<NMAGeoPolyline *> *multiPolylineArray |
NMACLE2GeometryPolygon | Represents a polygon with an NMAGeoPolygon for the outer ring and an array of NMAGeoPolygon for inner holes. Relates to a WKT polygon object containing all rings of this geometry. | NMAGeoPolygon *outerRing , NSArray<NMAGeoPolygon *> *innerRings |
NMACLE2GeometryMultiPolygon | Represents a multi-polygon as an array of NMACLE2GeometryPolygon . Relates to a MultiPolygon object in WKT. | NSArray<NMACLE2GeometryPolygon *> *multiPolygonArray |
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.

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:
NMACLE2GeometryType | Meaning |
---|---|
NMACLE2GeometryFull | The result contains the original geometry (as uploaded). This is the default. |
NMACLE2GeometryLocal | The result contains the processed geometry that falls within the search area for the tiles in reach. |
NMACLE2GeometryNone | No geometry is returned at all, only properties/attributes of geometries that match the given search are returned. |
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.