Using layers and working with polygons

Each geofence polygon, point, or polyline is assigned to exactly one layer. You can create multiple layers. A layer can only contain geometries of one type – either polygons, points, or polylines. This allows you to group the geofences by fence types or topics, or by asset groups.

If possible then submit or update all polygons of a layer in a single batch. The HERE Geofencing API supports adding or modifying of individual polygons, but only for storage type "updatable", not for "readonly".

Each customer can create multiple layers with many geometries per layer. For maximum values please refer to CLE's resource serviceconfiguration.json. If you need to need to extend the limits, please contact Technical Customer Support.

How to distribute the Geofences across map layers? While it seems obvious to create separate geofence layer per user/device/car, it is not efficient for the service. Usually, geofences of the same type (spatial extent, update frequency, coordinate resolution) should go together into a single layer. Each geofence should contain an attribute (or several ones) describing to which assets they apply (and some conditions, like timeframes), so customer’s application can filter which fences apply to the car/user. Being a backend service, Geofencing is usually not called by the users/devices directly, so it is not a privacy concern to return geofences of different cars/users to customer’s application. Also, different geometry types (circles vs polygons) should be stored in separate layers.

Polygon identifier and attribution

While the HERE Geofencing API is not intended to be used as general storage for data, the API must have access to geoshapes to respond to requests. Each of these geoshape must be associated with a unique identifier. The HERE Geofencing API also includes these IDs in the responses.

One common method for assigning these IDs uses straightforward geometry identifiers as follows:

• polygon ID for polygonal fences
• link ID for road, railway, river, or other linear fences
• point ID or store ID for point fences

In the following example, the column ID uniquely identifies the polygons near various famous locations.

ID    NAME    ABBR    WKT
1    AlexanderPlatz    DEU    POLYGON((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228))
2    BrandenburgGate    DEU    POLYGON((13.38021 52.51668,13.37987 52.51678,13.37984 52.5163,13.37984 52.5163,13.38021 52.51668))
3    RoyalObservatory    UK    POLYGON((-0.00156 51.47778,-0.00142 51.47796,-0.00114 51.47776,-0.00172 51.4777,-0.00156 51.47778))

When you use the resource search/proximity to see whether a geocoordinate is within a specified radius of a geoshape loaded to a layer, use the request parameter key_attributes to define how you wish to group the geoshapes in the response. For example, if you load the example above to a layer and specify key_attributes=NAME in your request, then the geoshapes within the radius are listed separately in the response as each value in the NAME column is unique. In this case, the response looks as follows:

{
    "geometries": [
        {
            "attributes": {
                "ID": "2",
                "GEOMETRY_ID": "1",
                "NAME": "BrandenburgGate",
                "ABBR": "DEU"
            },
            "distance": 640.79,
            "nearestLat": 52.51668,
            "nearestLon": 13.38021,
            "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)))"
        },
        {
            "attributes": {
                "ID": "1",
                "GEOMETRY_ID": "0",
                "NAME": "AlexanderPlatz",
                "ABBR": "DEU"
            },
            "distance": 1641.35,
            "nearestLat": 52.51981,
            "nearestLon": 13.41227,
            "geometry": "MULTIPOLYGON(((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
        }
    ],
    "response_code": "200 OK"
}

However, if you specify key_attributes=ABBR in the same situation, the response groups the results that match the request for those lines that match the specified ABBR value. In other words, if you specify ABBR=DEU, the results include lines 1 and 2 if the geocoordinate you are checking are within range of both. In this case, the response looks as follows:

{
    "geometries": [{
        "attributes": {
            "ID": "1",
            "GEOMETRY_ID": "0",
            "NAME": "AlexanderPlatz",
            "ABBR": "DEU"
        },
        "distance": 640.79,
        "nearestLat": 52.51668,
        "nearestLon": 13.38021,
        "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)),((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
    }],
    "response_code": "200 OK"
}

When you add a line 4 to the geoshapes as follows:

4    Reichstag    BER    POLYGON((13.37494 52.51885,13.37485 52.51948,13.3755 52.51817,13.3744 52.51757,13.37494 52.51885))

the API includes this geoshape in the response if the geocoordinate is within range, but in a separate group because the values were separate. In this case, the response looks as follows:

{
    "geometries": [
        {
            "attributes": {
                "ID": "1",
                "GEOMETRY_ID": "0",
                "NAME": "AlexanderPlatz",
                "ABBR": "DEU"
            },
            "distance": 640.79,
            "nearestLat": 52.51668,
            "nearestLon": 13.38021,
            "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)),((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
        },
        {
            "attributes": {
                "ID": "4",
                "GEOMETRY_ID": "3",
                "NAME": "Reichstag",
                "ABBR": "BER"
            },
            "distance": 871.25,
            "nearestLat": 52.51817,
            "nearestLon": 13.3755,
            "geometry": "MULTIPOLYGON(((13.37494 52.51885,13.37485 52.51948,13.3755 52.51817,13.3744 52.51757,13.37494 52.51885)))"
        }
    ],
    "response_code": "200 OK"
}

In short, you can use these column values in the same manner as SQL's group-by function.

You may also associate arbitrary attributes with geoshapes for use with your application. The API includes any values associated with a geoshape in the response. These custom attributes should be restricted only to those that the application needs. Examples include information that devices or management centers do not store locally but need to retrieve from queries, such as a display name or the priority of the fence geometry.

If you need to store a large amount of data along with the geometries, meaning the size of your geometries in Bytes are equal to or more than the size of your additional data, contact Technical Customer Support.