Geofencing Extension API

(1)

Geofencing Extension API

Developer's Guide

Version 1.2

(2)

► Contents

Legal Notices

...

4 Document Information

...

5 Chapter 1: Overview

...

6

What is the Geofencing Extension API?...7

Why use the Geofencing Extension API?...8

Chapter 2: Quick Start

...

10

Making your first request...11

Chapter 3: User Guide

...

13

Acquiring Credentials...14

Constructing a Request...14

Key Concepts...15

Examples...19

Example Submit Layer...19

Example Check...20

Service Support...21

Chapter 4: API Reference

...

22

Resources and Responses...23

Layer List Request...23

Layer List Response...23

Layer Upload Request...24

Layer Upload Response...25

Layer Put Request (Deprecated)...25

Layer Put Response...26

(3)

► Contents

Layer Delete Response...27

Search Proximity Request...28

Search Proximity Response...29

Check Request (Deprecated)...31

Check Response...32

Errors...34

(4)

► Legal Notices

Legal Notices

This material, including documentation and any related computer programs, is protected by copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of HERE. This material also contains confidential information, which may not be disclosed to others without the prior written consent of HERE.

Trademark Acknowledgements

HERE is trademark or registered trademark of HERE Global B.V.

Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

Disclaimer

This content is provided "as-is" and without warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, satisfactory quality and non-infringement. HERE does not warrant that the content is error free and HERE does not warrant or make any representations regarding the quality, correctness, accuracy, or reliability of the content. You should therefore verify any information contained in the content before acting on it.

To the furthest extent permitted by law, under no circumstances, including without limitation the negligence of HERE, shall HERE be liable for any damages, including, without limitation, direct, special, indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or application of this content, even if HERE or an authorized representative has been advised of the possibility of such damages.

(5)

► Document Information

Document Information

Product

Name: Geofencing Extension API

Version: Version 1.2

Document

Name: Geofencing Extension API Developer's Guide

Id: 6f07a86-1457603422

Status: FINAL

Date: 2016-Mar-10, 9:50 (GMT)

Signatory: O=HERE, CN=here.com, ST=Berlin, C=DE Issuer-Certificate: O=HERE, CN=here.com, ST=Berlin, C=DE Serial-No.: 17391143833054135595

method: urn:adobe.com:Adobe.PPKLite:adbe.pkcs7.sha1 (Adobe Signature)

(6)

► Overview

Chapter

1

Overview

Topics:

• What is the Geofencing Extension API?

• Why use the Geofencing Extension API?

This document introduces the Geofencing Extension API and: • explains key concepts

• provides examples

• documents resources and query parameters • documents response structures and data types

(7)

► Overview

What is the Geofencing Extension API?

The HERE Geofencing Extension API is a REST Web service to track whether or not mobile assets are within given geographic areas. Customers define geometries in the form of geographic polygons, polylines or points that are relevant for the assets. Customer can also choose to check their assets' position against Map layers, for example, postal code boundaries or census boundary layers.

Mobile assets keep sending their current positions to a management center. For each received asset position, the management center calls the HERE Geofencing Extension API to find out either in which relevant polygon(s) the asset lies, or close to which polygons, polylines or points within a defined search radius. The HERE Geofencing Extension API also returns the distance from the polygon borders it is (inside or outside) and the nearest polylines or points. The management center uses this for logging, statistics, alerts or to trigger activities.

Critical features are the supported amount of geofence polygons, their maximum geographic extend, their detail level (number of vertices and number of vertices per square meter), the number of mobile assets that regularly send position updates and the frequency of the updates, the required accuracy of the positions and support to suppress unwanted "flickering" notifications while an asset moves along a geofence border, and the average / maximum response time (notification delay). It is to be noted that a layer can contain only either polygons, points or polylines.

This Geofencing Extension API version provides the basic building block for geo fencing: A management center asks whether the position of an asset is within or close to a certain set of geometries, and gets a list of geometries also with the respective distances from the closest geometries (closest border, in case of a polygon). For performance reasons, the distances are only air distances (not driving distances or driving times), and they limited to roughly 20 kilometers. Some examples of such responses are:

• "within polygon 250m from the closest border" • "within polygon > 20km from the closest border" • "outside polygon 333m from the closest border" • "25m far from the point "

• or "outside polygon > 20km from the closest border"

(the last one is currently not returned by the service, it is the default i.e. applies to all non-listed geometries). The main use case of the distances is generating pre-warnings (of lower priority) and to suppress repeated "flickering" warnings while the asset is close to a border.

(8)

► Overview

Geofencing Extension API stores the geometries which are grouped into layers. It is also possible to geo-fence over Map layers. Passing a coordinate and a layer (either custom layer or Map layers), the management center asks in which geometries of a this layer the coordinate is (with distances, including outside-but-close situations, see above).

Subsequent service versions will store rules, assets and time windows. Then, a management center can provide an asset id and a coordinate to get this list of Geometries.

Geofencing Extension API responds to "check" requests. Based on the response, a management center can raise alerts, notify the device and take appropriate actions.

Why use the Geofencing Extension API?

Geofencing Extension API provides solutions for the following high level use cases: Table 1: Main use cases of the HERE Geofencing Extension API

Feature Description

No-Go Areas in Cities Certain areas in cities shall not be accessed by assets (e.g. kids, young women, luxury cars...), within certain times (of day ... or week). For each asset group there is a rather static set of polygons defined, and the assets and/or the management system shall be alerted if an asset approaches or enters such an area. The polygons can have individual validity time windows.

(9)

► Overview

Feature Description

Alert Warehouse 15 Minutes before Truck Arrives

To prepare for a delivery, warehouses want to be notified if a mobile asset (truck) is less than 15 minutes away. The isochrone polygons around each warehouse can be static (computed by HERE reverse isoline routing), or dynamic according to either (weekly reoccurring) traffic patterns or the current live traffic situation. The validity period of each polygon can be the warehouse opening hours.

Notify Parents if Kids Leave their Kindergarten / Playground / Grandmother's House

For each mobile asset (child, old people, prisoner, animal, vehicle...), a rather static (mostly) individual set of polygons or points is defined with certain time windows. Depending on the distance to a polygons border or to a point, alarms with different priorities can be raised.

Asset Rental Agency wants Notification if an Asset enters a forbidden country or area

Certain groups of rental cars are rented with a restricted set of allowed countries/areas for insurance policy or security reasons. A few static polygons with a big geographic extend and rather fine grained resolution (hence number of vertices) are defined per asset group. Taxi Service wants Notification

if there are less than 5 Cars within a Hot Spot Polygon

In the vicinity of a train station or a stadium after a big event there should be sufficient cars within 3 minutes reach to be ordered by end users. Many static and a few dynamic polygons are defined. Critical for alerts are not individual assets but the total number of assets within a polygon. In this version of the service, fleet management systems must maintain the counts per polygon themselves and trigger alerts in case of underflow. In a subsequent version, the service might provide this functionality.

Alert End User 15 Minutes before he Receives a Package

To prepare for a postal or drone delivery, end users want a notification if a mobile asset (delivery truck/person/drone) is less than 15 minutes away. End users are entered on the fly as isochrone polygons, as soon as the delivery starts. Each mobile asset is checked against one end user polygon.

Alert Consumer when he is close to a Shop (Advertising)

While the mobile asset is moving (car driver or shopping pedestrian), alert him with an advertisement, if he gets close to a shop or restaurant. The validity periods of each rather static polygon or point are the opening hours of the business.

(10)

► Quick Start

Chapter

2

Quick Start

Topics:

• Making your first request

(11)

► Quick Start

Making your first request

Sometimes the easiest way to start using new software is to run simple examples.

The examples in this guide use the Customer Integration Testing (CIT) environment. This environment allows you to test your software. For production please use the production environment. See

Constructing a Request on page 14 for the base URLs of both environments.

Note that most example URLs in this guide are broken up into multiple lines for better readability. Remove these line breaks and spaces when copying and pasting the examples to make sure URLs are still well formed.

Prerequisites

The only thing you need to start using the Geofencing Extension API is an HTTP client. Choose any HTTP client application you are familiar with. A command line tool like curl will do the job, as will any

modern web browser.

Upload Geofences

In order to be able to use the Geofencing Extension API, one or more geofencing polygons needs to be uploaded to the service. Shapefiles or WKT files can be uploaded via a POST request to the following URL: https://gfe.cit.api.here.com/1/layers/upload.json ?app_id={YOUR_APP_ID} &app_code={YOUR_APP_CODE} &layer_id=123

The POST request must contain a multipart "files" parameter with a zip file containing the shape files or the WKT file.

Check for coordinate inside/outside of geofence

To check if an asset is inside or outside of the uploaded geofence polygon(s) the search proximity interface can be used:

https://gfe.cit.api.here.com/1/search/proximity.json ?app_id={YOUR_APP_ID}

&app_code={YOUR_APP_CODE} &layer_ids=123

(12)

► Quick Start

&proximity=50.166078,8.53419,500

The response contains the attributes and distance of the geofences the provided coordinate is in or nearby. Positive distances indicates the position is outside and that amount of meters away from the closest border of the geofence, negative distances indicate that the position is inside the geofence and that amount of meters away from the closest border of the geofence. The search radius can be set by the parameter 'search_radius' in meters. Geofences more than search_radius away from the coordinate are not mentionend in the result. Geofences, which include the coordinate, but the coordinate is more than search_radius meters away from the closest border, are listed in the result with a defined constant value.

Response

{ "errors":[], "warnings":[], "requestId":"469b08f3-2838-49d3-912d-4adf81d6e93c", "geometries":[ { "distance":655.66, "nearestLat":50.0, "nearestLon":8.0, "attributes": { "POSTCODE":"2009", "ADMIN4":"Sydney", ... } }, { "distance":-99999999, "nearestLat":50.1, "nearestLon":8.1, "attributes": { "POSTCODE":"2000", "ADMIN4":"Sydney", ... } } ], "onError":false }

The response can contain more custom attributes which were uploaded together with the geofence polygons. For more examples see Examples on page 19

(13)

► User Guide

Chapter

3

User Guide

Topics: • Acquiring Credentials • Constructing a Request • Key Concepts • Examples • Service Support

The articles in this section provide a guide to using the Geofencing Extension API.

(14)

► User Guide

Acquiring Credentials

All users of HERE Extension APIs must obtain authentication and authorization credentials and provide them as values for the parameters app_id and app_code. The credentials are assigned per application.

This document uses the placeholder text {YOUR_APP_CODE} and {YOUR_APP_ID} as placeholders for access and authorization credentials. Please replace these placeholders with your own unique application-specific credentials to access the API resources.

To obtain the credentials for an application, please contact us.

If you wish to explore the API, use the API Explorer at https://developer.here.com/api-explorer.

Constructing a Request

A request to the Geofencing Extension API includes the basic elements shown in the following table and, in addition, it may contain resource-specific parameters or data.

Table 2: Basic request elements

Element Value/Example Description

Base URL

https://gfe.api.here.com https://gfe.cit.api.here.com https://maps.gfe.api.here.com https://maps.gfe.cit.api.here.com

.cit. = Staging environment only [1], otherwise production environment only.

maps. = Map layers, otherwise customer layers.

Path /1/

Resource /1/search/proximity.json Query which geo fence geometries of a certain layer cover or are close to the given asset position.

GET only, specify request details via query parameters

Resource /1/layers/upload.json Submit a new layer with a set of geo fence geometries, or replace the existing layer.

(15)

► User Guide

Element Value/Example Description

POST - submit data in the body of the request, or GET - submit data as (zipped or plain) base64 encoded string.

Application Code &app_code={YOUR_APP_CODE} Substitute your own unique app_code

Application Id &app_id={YOUR_APP_ID} Substitute your own unique app_id

[1] The staging environment allows you to test your software against a newer version of the service before HERE brings that version into production. Note that the same application id can be used in both environments, but staging may require a dedicated application code. If this is the case, please contact us as described under Service Support on page 21.

The staging environment is not intended for production use and HERE SLAs do not apply for this environment.

Key Concepts

This section provides insights into the key concepts used throughout the Geofencing Extension API.

Layers

Customers can create multiple layers. Each geo fence polygon, point or polyline is assigned to exactly one layer. A layer can contain geometries of only one type (either polygons, points or polylines).This allows applications to group the geo fences by fence types/topics and by asset groups. All polygons of a layer must be submitted or updated in a single batch, individual polygon additions or modifications are currently not supported.

There are technical limitations on the number of layers per customer. If more than 100 layers are required, customers should discuss this with Technical Customer Support upfront.

There are technical limitations on the number of geometries per layer. If more than 10,000 geometries in a single layer are required, customers should discuss this with Technical Customer Support upfront. Also the number of vertices per polygon and the total number of vertices across all geometries of the layer is limited, see below.

(16)

► User Guide

In / Out / Distance and Search Radius

For each geo fence that covers the asset position (only for polygons), or is close to the asset position, the geo fence geometry is returned, together with the asset distance to the geometry. If the asset is outside (for line and point geo fences it is always outside), then the distance is the airline to the closest border of the geo fence. Also, if the asset is inside, then the distance is the airline to the closest border of the polygon, just with a negative sign. If the asset is further away than the radius of interest (search radius), the geo fence is not listed in the response. If the asset is inside the polygon, but further away from the border than the radius of interest, a special value "far inside" is returned.

Providing a distance instead of just in/out allows for more use cases: Applications can generate events with different severity levels for certain distance thresholds. And applications can suppress superfluous events if the asset if "walking along the geo fence border", so entering/leaving frequently without significant change in the distance.

For performance reasons, the distances are only air distances (not driving distances or driving times) and they limited to roughly 20 kilometers, so a distance can be "within polygon 250m from the closest border", "within polygon > 20km from the closest border", "outside geo fence 333m from the closest border" or "outside geo fence > 20km from the closest border" (the last one is currently not returned by the service, it is the default i.e. applies to all non-listed geo fences).

Events (like entering, leaving, flickering along the border, re-entering...) are not explicitly returned, just distances. The same applies to sequences of events (like entered 3rd time, left 2nd time within a day...).

Geo Fence Upload Format

A set of geo fence geometries is uploaded atomically into a layer. Therefore a zip archive is passed that contains the geometry file. Supported file formats are Shapefile and WKT, supported geometry types are Polygon, Multi Polygon, Point and Polyline.

In case of Shapefile, the zip archive must at least contain the .shp, .shx and .dbf files, and can optionally also contain .cpg (character set definition) and .prj (geo coordinate system and projection) files, where the defaults are UTF-8 and WGS84.

A WKT file is a tab separated plain text file with file name suffix ".wkt". The first line defines the attribute (column) names and must include a "WKT" attribute. The subsequent lines contain the data. The WKT attribute must be in WKT text format and rings must be closed. For attribute values, empty strings can be used, but NULL values for unknown or non-existing values are not supported. Example WKT file content:

(17)

► User Guide 20300625 751498000 3 POLYGON ((1.73514 42.5498, 1.73619 42.55064, 1.73663 42.55115, ... 1.73514 42.5498)) 20128885 751118953 5 POLYGON ((15.60834 46.68781, 15.60865 46.68766, ... 15.60834 46.68781))

For both Shapefile and WKT formats, the only supported geo coordinate system is plain WGS84 without projection. Using LAT or LON as attribute (column) names should be avoided, and the attributes might appear renamed to _LAT, _LON in the "check" responses.

Geometry Size and Resolution

The size (spatial extent) of a geo fence (polygon or polyline) can reach from a few square meters to a 100 km into each dimension. In addition, a geo fence should not contain more than 100,000 vertices, and the total number of vertices of all geometries of a layer should not exceed 1,000,000. To avoid unwanted artefacts from rounding or algorithmic accuracy, the resolution of the polygon coordinates should not be more fine grained than 2/100,000 of a WGS84 degree (roughly 2 meters). If Geometries (polygons or polylines) contain vertices less than roughly 2 meters apart from each other, then the geometries might get slightly simplified or distorted by the service.

Polygon Identifier and Attribution

Geofencing Extension API is not intended as a general data store for geo fence entities. It mainly needs to know the geometries to answer the queries on asset positions. However, it requires a unique geometry identifier attribute (column) for the geometry. These ids are returned in the query responses.

Most applications use the straightforward geometry identifier, like "polygon ID" for polygonal fences, "link ID" for road, railway, river or other linear fences and "point ID" or "store ID" for point fences. However, any of the geofence attributes can be used in a geofence request. E.g. specifying the "name" attribute for road links layer returns one result distance and polyline and one distance for each distinct road name, instead of returning the distance and geometry for each road link separately. Or specifying "store_brand_name" returns one distance and fence geometry per different brand, meaning "80m to the nearest Tesco store, 120m to the nearest BP station shop" without listing each of the Tesco shops around separately. So, basically the identifier attribute can be used like the SQL "group by" function.

In addition to the identifier attribute, geo fence geometries can be submitted with arbitrary custom attributes, that can be returned along with the geometry identifiers in the queries. These attributes should be restricted to what is actually needed by the application, i.e. info that devices or management centres don't store locally but must retrieve from the queries, like a display name or the importance of the fence geometry. Customers who need to store a big amount of data along with the

(18)

► User Guide

geometries (byte size above or within the same order of magnitude as the geometry) should discuss this with technical customer support upfront.

Retrieving Geo Fence Geometry

The Geofencing Extension API assumes that the application knows the geometry itself, in order to display or modify it. So, by default queries return only the id of each geometry. Returning the full fence geometries in each query would create an excessive amount of network traffic and slow down device and service.

However, to support a simple display in devices and asset manager centres, Geofencing Extension API optionally returns the relevant fragments of the geometry - the part that is within the query search radius. But even this can cause excessive load, so applications shall cache the geometry piece of recently displayed geometries, and only if a non-cached geometry id is returned, or the asset moved a lot since the last cached geometry fragment, then the query should be resent with requesting the geometry fragments.

Frequency of Requests

There is no restriction on the frequency querying for the geo fences around a changed asset position. However, to reduce the load on the device, network and service, applications should utilize the distances returned by the service, in order to suppress unnecessary calls, if it is clear that compared to the last query the asset's geo fencing status cannot have changed. E.g. if the closest geometry distance was 3.5 km, and the car moved by 100 meters, then it cannot have left or entered a geo fence, so it is sufficient to query less frequently just to not miss changes in the geo fences on the server side.

Rules

A geo fencing rule defines, which assets are related to which geometries at what time frames, e.g. whether they must stay inside or outside of the polygon(s) or near or far away from a point/polyline. The current Geofencing Extension API version does not support definition of rules. It only supports grouping germetries within layers, and queries must refer to a layer of interest.

Assets

An asset is any kind of trackable object, e.g. person, car, smartphone or delivery package. The current Geofencing Extension API version does not require or support asset identification or registration.

(19)

► User Guide

Map Layers as Geo Fences

In addition to creating customer specific proprietary private layers, customers can also use map layers as geo fences. For example, postal code polygons, country boundary polygons, railroad track or road lines, lakes and river polygons + polylines or points of interest can be used for geo fencing. Map layer coverage = PDE coverage: All map layers for all geographic regions for all map releases are available for geo fencing that PDE offers.

Please note that different commercial terms apply for using map layers as geo fences.

Examples

This section provides examples of requests along with the responding results.

Example layers/upload

User Story

The customer has created or modified the geo fence polygons of a layer, and stored them in a Shapefile or WKT text file. To deploy them, he submits the zip archive of the file (actually several files in case of Shapefile format) to Geofencing Extension API.

Request Summary

The following list summarizes the elements required to create a request matching the user story and shows, in square brackets, how those elements are used in the request example below. Note that the request example also uses the authentication parameters.

Resource: layers/upload

Parameters:

layer_id [4711], a user defined integer value to identify the layer for subsequent 'proximity' requests.

Request

curl --request -i -X POST -H "Content-Type: multipart/form-data"

(20)

► User Guide -F "files=@C:\temp\layer_4711_shapes.zip" "https://gfe.cit.api.here.com /1/layers/upload.json ?layer_id=4711 &app_id={YOUR_APP_ID} &app_code={YOUR_APP_CODE} "

Response

The response is empty.

Example Check if Coordinate inside Geo Fences

User Story

The user wants to check in which geo fence polygons a coordinate resides, and which distance it has to the polygons.

Request Summary

The following list summarizes the elements required to create a request matching the user story and shows, in square brackets, how those elements are used in the request example below. Note that the request example also uses the authentication parameters.

Resource: search/proximity

Parameters:

layer_ids [4711], which set of geo fence polygons to search. proximity [50.0,8.0,500], latitude, longitude of asset position coordinate, and optionally search radius.

attributes [FENCE_ID,NAME], attributes to return for each geo fence.

keyattribute [FENCE_ID], attribute that identifies a geo fence in the layer.

Request

https://gfe.cit.api.here.com/1/search/proximity.json ?layer_id=4711 &app_id={YOUR_APP_ID} &app_code={YOUR_APP_CODE} &proximity=50.0,8.0,500 &keyattribute=POSTCODE

(21)

► User Guide

Response

{ "errors":[], "warnings":[], "requestId":"469b08f3-2838-49d3-912d-4adf81d6e93c", "geometries":[ { "distance":655.66, "nearestLat":50.0, "nearestLon":8.0, "attributes": { "POSTCODE":"2009", "ADMIN4":"Sydney", ... } }, { "distance":-99999999, "nearestLat":50.1, "nearestLon":8.1, "attributes": { "POSTCODE":"2000", "ADMIN4":"Sydney", ... } } ], "onError":false }

Service Support

If you need assistance with this or other HERE products, please contact your HERE representative or Technical Customer Support.

(22)

► API Reference

Chapter

4

API Reference

Topics:

• Resources and Responses

• Errors

This section provides descriptions of the resources, parameters, return types and error codes of the HERE Geofencing Extension API.

(23)

Resources and Responses

All parameter values including letters outside A-Z and a-z must be first UTF-8 encoded and then URL encoded. Every URL unsafe character should be URL encoded.

Responses can be extended by new elements or attributes without prior announcement, and without a new major version. Hence, applications that parse the responses should not assume fixed response structures, but should deal with additional, unexpected elements and attributes.

Layer List

Resource URI

/layers/list.json

Resource Parameters

Parameter Type Mandatory Description

app_id string Y _{Typically, but not guaranteed to be, 20 bytes Base64 URL-safe} encoded string used for the authentication of the client application. See Acquiring Credentials.

app_code string Y Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.

callback string N Specifies the name of a user-defined function used to wrap the JSON response. Required for JSONP requests.

Default: No JSONP response wrapper

Response Elements / Attributes

(24)

issues List of elements with following attributes

Y Lists issues encountered during processing. If this list is not empty, then the application must not use the response content.

issues . message

string Y Text description of the issues.

issues . code integer Y Numeric error code for the issue, either for one single issue or for a category of issues.

warnings List of plain text warnings.

Y Lists warnings encountered during processing. Even if this list is not empty, the application can use the response content.

errorId string N If errors occurred during processing, then this id can be passed on to Technical Customer Support for further investigation.

responseCode string N HTTP response code and response text.

onError boolean Y True, if errors occurred during processing and the result must not be used.

Layers Upload

Resource URI

/layers_upload.json

Resource Parameters

app_id string Y Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.

layer_id string Y Upload the geometries into this layer, or replace all existing geometries in this layer.

file string N Only for GET requests. The file that is usually sent in the POST request body, can alternatively be sent in this GET request parameter. The file can be plain or zipped, and it has to be URL-encoded or Base64 encoded. Please note that Web browsers, intermediate firewalls and routers as well as the backend service impose limits on the total size

(25)

of a GET request URL. Hence this option should only be used for small demos.

Response Elements / Attributes

storedTilesCount Number Y Returns the number of objects stored. Note that this number can be higher than the number of submitted geometries, because it counts tiles pieces of geometry.

issues . message

responseCode string N _{HTTP response code and response text.}

Layer Put - DEPRECATED - Please use /search/

proximity instead!

Resource URI

/layer_put.json

(26)

Resource Parameters

layer_id integer Y Upload the geometries into this layer, or replace all existing geometries in this layer.

file string N Only for GET requests. The file that is usually sent in the POST request body, can alternatively be sent in this GET request parameter. The file can be plain or zipped, and it has to be Base64 encoded. Please note that Web browsers, intermediate firewalls and routers as well as the backend service impose limits on the total size of a GET request URL. Hence this option should only be used for small demos.

Response Elements / Attributes

errors List of elements with following attributes

Y Lists errors encountered during processing. If this list is not empty, then the application must not use the response content.

errors . type integer Y Type for the error. In this versions, no error types are defined. errors .

message

string Y Text description of the error.

errors . code integer Y Variable value for a variable specified in the text, specific for the error type.

requestId string N _{If errors occurred during processing, then this id can be passed on to} Technical Customer Support for further investigation.

(27)

Layers Delete

Resource URI

/layers/delete.json

Resource Parameters

layer_ids list of integers Y _{Comma separated list of the slected layer ids.}

Default: No JSONP response wrapper

Response Elements / Attributes

layers Layer list Y List of the deleted layers. issues List of elements

with following attributes

issues . message

(28)

responseCode string N HTTP response code and response text.

Search Geometries close or including the given

Coordinate

Resource URI

/search/proximity.json

Resource Parameters

layer_ids list of integers Y Comma separated list of the slected layer ids.

proximity string Y Asset GPS position latitude and longitude in WGS84 degree, comma separated, and optionally a radius im meter. The radius defines how far to search around the asset position for geo fence geometries. Default raduis = 1,000 meter, maximum = 20,000 meters.

attributes string N Semicolon separated list of attribute names to be returned with the geometries. Default: Return all attributes. If all listed attributes are preceded with a minus, then all attributes except those are returned. keyattributes string Y Names of the attributes that identify each geometry. Comma

separated. See Key Concepts on page 15 for possibilities to use this

parameter.

(29)

Response Structure

{ issues : [ { message : "...", code : ... }, ... ], warnings : [ "...", ... ], error_id : "...", response_code : "...", geometries : [ { layerId : "...", distance : ..., nearestLat : ..., nearestLon : ..., attributes : { <attribute name 1> : "...", <attribute name 2> : "...", ... }, geometry : "..." }, ... ], onError : ... }

Response Elements / Attributes

issues . message

(30)

responseCode string N HTTP response code and response text. geometries List of elements

with following attributes

Y Lists the fence geometries that contain the asset position or overlap the search_radius circle around the asset position. For each distinct value of the keyattribute given in the request, only 1 result geometry is returned. This allows applications to submit a geo fence geometry comprising multiple faces (separate top level rings) which are treated like one geometry, i.e. only one distance - to the closest line of all its rings - is returned. See Key Concepts on page 15.

geometries . layerId

string Y The layer the geofoence geometry belongs to.

geometries . distance

float Y Distance of the asset position to the closest border line of the polygon, point or point on the polyline. If the asset is outside, then the distance is positive, and negative if inside. If the asset is inside the polygon, but more than search_radius away from the closest polygon border line, point or polyline, then the value is -99,999,999.

geometries . nearestLat

float Y Latitude of the nearest point of the geometry/geometry border. Void if distance = -99,999,999.

geometries . nearestLon

float Y Longitude of the nearest point of the geometry/geometry border. Void if distance = -99,999,999. geometries . attributes List of elements with the attributes chosen in the request.

Y Lists fence geometry attributes.

geometries . geometry

Geo fence geometry

N Geo fence geometry in WKT MultiPolygon, MultiLineString or MultiPoint format. The geometry is not necessarily the original polygon or polyline geometry. Depending on the value of the request parameter 'geom' it can be parts of the polygon or polyline. In general a polygon or polyline can be returned as several pieces.

For polygones, leading zeroes in the longitude coordinates indicate that the line to the next coordinates is not part of the full polygon's border, but an artificial internal line, e.g. from clipping the polygon. Filled drawing should draw all pieces. When drawing polygon borders, the lines from coordinates with leading zeroes shouldn't be drawn. onError boolean Y True, if errors occurred during processing and the result must not be

(31)

Check Asset Position against Geo Fences Request

-DEPRECATED - Please use /search/proximity instead!

Resource URI

/check.json

Resource Parameters

app_code string Y _{Typically, but not guaranteed to be, 20 bytes Base64 URL-safe} encoded string used for the authentication of the client application. See Acquiring Credentials.

layer_id integer Y Check the position against all the geometries of this layer. Either layer_id or layer_ids must be specified. Alternatively or in addition, maplayer or maplayers can be specified.

layer_ids list of integers Y _{Comma separated list of the slected layer ids.}

maplayer integer Y Check the position against all the geometries of this map layer. The available map regions, map layers and map releases can be obtained from PDE.

Either layer_id or layer_ids must be specified. Alternatively or in addition, maplayer or maplayers can be specified.

maplayers list of integers Y _{Check the position against all the geometries of the comma separated} list of map layers. The available map regions, map layers and map releases can be obtained from PDE.

Either layer_id or layer_ids must be specified. Alternatively or in addition, maplayer or maplayers can be specified.

lat float Y Asset GPS position latitude in WGS84 degree. lon float Y _{Asset GPS position longitude in WGS84 degree.}

search_radius float N Radius around the asset position to search for geo fence geometries. Meters. Default 1000 meters. Maximum value 20,000 meters.

(32)

attributes string N Semicolon separated list of attribute names to be returned with the geometries. Default: Return all attributes. If all listed attributes are preceded with a minus, then all attributes except those are returned. keyattribute string Y Name of the attribute that identifies each geometry. See Key

Concepts on page 15 for possibilities to use this parameter. geom string N If value = 'local', then the response returns a WKT MultiPolygon with

faces that roughly comprise the parts of the full geo fence geometry that are within the search radius. Default: Do not return geometry.

Response Structure

{ errors : [ { type : "...", message : "...", code : ... }, ... ], warnings : [ "...", ... ], requestId : "...", geometries : [ { distance : ..., nearestLat : ..., nearestLon : ..., attributes : { <attribute name 1> : "...", <attribute name 2> : "...", ... }, geometry : "..." }, ... ], onError : ... }

(33)

Response Elements / Attributes

errors List of elements with following attributes

Y Lists errors encountered during processing. If this list is not empty, then the application must not use the response content.

errors . type integer Y Type for the error. In this versions, no error types are defined. errors .

message

string Y Text description of the error.

errors . code integer Y Variable value for a variable specified in the text, specific for the error type.

requestId string N If errors occurred during processing, then this id can be passed on to Technical Customer Support for further investigation.

geometries List of elements with following attributes

Y Lists the fence geometries that contain the asset position or overlap the search_radius circle around the asset position. For each distinct value of the keyattribute given in the request, only 1 result geometry is returned. This allows applications to submit a geo fence geometry comprising multiple faces (separate top level rings) which are treated like one geometry, i.e. only one distance - to the closest line of all its rings - is returned. See Key Concepts on page 15.

geometries . distance

float Y Distance of the asset position to the closest border line of the polygon, point or point on the polyline. If the asset is outside, then the distance is positive, and negative if inside. If the asset is inside the polygon, but more than search_radius away from the closest polygon border line, point or polyline, then the value is -99,999,999.

geometries . nearestLat

float Y Latitude of the nearest point of the geometry/geometry border. Void if distance = -99,999,999.

geometries . nearestLon

float Y Longitude of the nearest point of the geometry/geometry border. Void if distance = -99,999,999. geometries . attributes List of elements with the attributes chosen in the request.

Y Lists fence geometry attributes.

geometries . geometry

Geo fence geometry

N Geo fence geometry in WKT MultiPolygon, MultiLineString or MultiPoint format. The geometry is not necessarily the original polygon or polyline geometry. Depending on the value of the request parameter

(34)

'geom' it can be parts of the polygon or polyline. In general a polygon or polyline can be returned as several pieces.

For polygones, leading zeroes in the longitude coordinates indicate that the line to the next coordinates is not part of the full polygon's border, but an artificial internal line, e.g. from clipping the polygon. Filled drawing should draw all pieces. When drawing polygon borders, the lines from coordinates with leading zeroes shouldn't be drawn. onError boolean Y True, if errors occurred during processing and the result must not be

used.

Errors

Geofencing Extension API can return several types of errors, which are shown in the table below.

Status Message Error (description) Details (example)

Bad Request Missing Parameters

Required Parameters have not been provided.

Bad Request There was a unique key violation. Check data input.

Duplicate entry [value] for key [field]

Bad Request Invalid Authentication

Incorrect authentication credentials given in the request. See Acquiring Credentials for

more information. 400 Bad Request Unable to complete request

Diagnostic text. Further information about the cause of the error.

Unauthorized User not authorized for this action.

"User does not have permission rights for export" or "User not authorized for this action".

(35)

► Coverage Information

Chapter

5

Coverage Information

The currently available maps (supported geographic regions and map releases) for geo fencing on map layers is identical to the PDE Web service and can be looked up there.