Geofencing Extension API Developer's Guide

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.

Always submit or update all polygons in a layer in a single batch. The Geofencing Extension API does not support adding or modifying individual polygons.

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.

Polygon Identifier and Attribution

While the Geofencing Extension 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 Geofencing Extension 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.

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.