HERE iOS SDK Developer's Guide

Custom Location Extension 2

Custom Location Extension 2 (CLE2) allows you to easily distribute custom geospatial information by uploading geometry data in a Shapefile or well-known text (WKT) file, and then query for them from the HERE iOS SDK or the CLE2 web API. Custom Location geospatial data is uploaded to the HERE servers as distinct user-defined layers. When a user needs to query or download the geospatial information, they can specify a layer where this action occurs.

Some examples of how you can use these CLE2 features include:

  • Show all users' custom Points of Interest (POIs) within a 2km radius.
  • Search for all HERE offices within Germany using an area defined by a polygon, then display the reception's phone number, employees count, and other details.
  • Cache and show all POIs or geometries that intersect with a user-defined bounding box, circle, or polygon shape.
  • Search for specific types of objects that are near a given route.

Search functionalities that previously required an internet connection are also available offline. If enabled, this effectively makes the HERE iOS SDK a lightweight spatial data storage solution.

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/versions#custom-location.

Layers and Filtering

All data is organised 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.

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

Performing Spatial Searches

The classes that support this feature are located in the NMA_CLE2 group. In CLE2, instead of having specific methods for either Location or Geometry requests, we unify all use cases in one flexible approach: the returned value always contains one of the geometry types (the simplest being an NMACLE2GeometryPoint), along with a set of 0 to N user-defined attributes that can represent anything, such as a POI or an address. There is no implied structure for these attributes. These attributes are made available as an NSDictionary.

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

Table 1. Search Classes
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 falls within a specified QuadKey. NMACLE2QuadkeyRequest
Attribute Retrieve all geometries that matches with a specified query. This type of search is only available online. NMACLE2AttributeRequest
Table 2. Common Request Arguments
Property Description Example Values
geometryType Specifies the geometry type to be given in the result (online only), see details below on "Understanding the search results"
  • NMACLE2GeometryFull
  • NMACLE2GeometryLocal
  • NMACLE2GeometryNone
requestMode Specifies the request mode. NMACLE2Online mode is the default. NMACLE2Automatic prioritises online mode, but falls back to offline if the connection is interrupted or unavailable. NMACLE2Offline uses the locally stored data only.
  • NMACLE2Online
  • NMACLE2Offline
  • NMACLE2Automatic
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 passes the filter are returned. Accepted strings are free form text with simple equality and comparison operators.  

After performing a search, check for the contents of the NMACLE2Result geometriesArray property. This array may contain one or more of the following object types:

Table 3. Geometry Return 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 a 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 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 that the class NMACLE2GeometryPolygon contains a NMAGeoPolygon and a secondary NMAGeoPolygon array.

Note: Custom Locations search is restricted by App Id and App Code for each layer. To manage the access restrictions of a Custom Locations layer, contact your Custom Location administrator. If you do not have one, contact your HERE customer representative.

CLE2 Map Example

The following images show an example of CLE2, with the user-uploaded geometries of two points (NMAMapMarker), one polyline in the shape of the letters "HERE" (NMAMapPolyline), and one polygon (NMAMapPolygon). These geometries are then overlaid with the visualized representations of two queries — a proximity and a corridor search request.

Figure 1. User-uploaded Custom Geometries

In this next image, the green circle represents the proximity search area projected on the Earth's surface.

Figure 2. Proximity search request: All geometries within a 300m radius

In the following image, the rendered corridor area (in green) is generated from the user-given polyline (a set of geographical coordinates) and a radius.

Figure 3. Corridor search request: All geometries as far as 50 meters from a given polyline

Proximity Search Request Example

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

A 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 a search for all locations in the previously-mentioned stores layer that exists within a 8 kilometer 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, the "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 a 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 the 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 expression that is evaluated for each location-matching search query. When specified, only the geometries that the expression evaluates to true, such as 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 the 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.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.