Geofencing Extension API

Transcription

1 Geofencing Extension API Developer's Guide Version 1.1

2 Geofencing Extension API Developer's Guide 2 Contents Contents Legal Notices...3 Document Information... 4 Chapter 1: Overview... 5 What is the Geofencing Extension API?... 6 Why use the Geofencing Extension API?... 7 Chapter 2: Quick Start... 9 Making your first request...10 Chapter 3: User Guide...12 Acquiring Credentials...13 Constructing a Request Key Concepts...14 Examples...17 Example Submit Layer Example Check...19 Service Support Chapter 4: API Reference...21 Resources and Responses Layer Put Request Layer Put Response...23 Check Request...23 Check Response Errors...26

3 Geofencing Extension API Developer's Guide 3 Legal Notices Legal Notices 2015 HERE. All rights reserved. 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 and Nokia are trademarks or registered trademarks of Nokia Corporation. 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.

4 Geofencing Extension API Developer's Guide 4 Document Information Document Information Product Name: Geofencing Extension API Version: Version 1.1 Document Name: Id: Status: Date: Geofencing Extension API Developer's Guide bafcd FINAL 2015-Nov-25, 14:20 (GMT)

5 Geofencing Extension API Developer's Guide 5 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

6 Geofencing Extension API Developer's Guide 6 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.

7 Geofencing Extension API Developer's Guide 7 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 No-Go Areas in Cities Description 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.

8 Geofencing Extension API Developer's Guide 8 Overview Feature Alert Warehouse 15 Minutes before Truck Arrives Notify Parents if Kids Leave their Kindergarten / Playground / Grandmother's House Asset Rental Agency wants Notification if an Asset enters a forbidden country or area Taxi Service wants Notification if there are less than 5 Cars within a Hot Spot Polygon Alert End User 15 Minutes before he Receives a Package Alert Consumer when he is close to a Shop (Advertising) Description 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. 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. 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. 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. 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. 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.

9 Geofencing Extension API Developer's Guide 9 Quick Start Chapter 2 Quick Start Topics: Making your first request This article helps you start using the Geofencing Extension API.

10 Geofencing Extension API Developer's Guide 10 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 13 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 Geofence 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: &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 positionchanged interface can be used: &app_code=your_app_code} &layer_id=123 &keyattribute=postcode

11 Geofencing Extension API Developer's Guide 11 Quick Start &lat= &lon= &search_radius=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":"469b08f d3-912d-4adf81d6e93c", "geometries":[ "distance":655.66, "nearestlat":50.0, "nearestlon":8.0, "attributes": "POSTCODE":"2009", "ADMIN4":"Sydney",... } }, "distance": , "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 17

12 Geofencing Extension API Developer's Guide 12 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.

13 Geofencing Extension API Developer's Guide 13 User Guide Acquiring Credentials All users of HERE 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 visit for more details. If you wish to explore the API, use the API Explorer at 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 Production environment only Staging environment only [1] Path /1/ Resource /1/check.json Query which geo fence polygons of a certain layer cover the given asset position. GET only, specify request details via query parameters Resource /1/layer_put.json Submit a new layer with a set of geo fence polygons, or replace the existing layer. POST - submit data in the body of the request, or GET - submit data

14 Geofencing Extension API Developer's Guide 14 User Guide Element Value/Example Description 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 20. 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. 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

15 Geofencing Extension API Developer's Guide 15 User Guide 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: ADMIN_PLACE_ID CARTO_ID NLP_ZOOM_LEVEL WKT POLYGON (( , , , )) POLYGON (( , , ))

16 Geofencing Extension API Developer's Guide 16 User Guide 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 can reach from a few square meters to a whole country or continent. Currently, there is no restriction on the size of a geo fence polygon or polyline. However, 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. In addition, 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 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

17 Geofencing Extension API Developer's Guide 17 User Guide 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. 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.

18 Geofencing Extension API Developer's Guide 18 User Guide Example layer_put 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: layer_put Parameters: layer_id [4711], a user defined integer value to identify the layer for subsequent 'check' requests. Request curl --request -i -X POST -H "Content-Type: multipart/form-data" -F "files=@c:\temp\layer_4711_shapes.zip" " /1/layer_put.json?layer_id=4711 &app_id=your_app_id} &app_code=your_app_code} " Response The response is empty.

19 Geofencing Extension API Developer's Guide 19 User Guide 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: check Parameters: layer_id [4711], which set of geo fence polygons to search. lat [50.0], latitude of asset position coordinate. lon [8.0], longitude of asset position coordinate. search_radius [500], radius aoriund asset position to search for nearby geo fences. attributes [FENCE_ID,NAME], attributes to return for each geo fence. keyattribute [FENCE_ID], attribute that identifies a geo fence in the layer. Request &app_id=your_app_id} &app_code=your_app_code} &lat=50.0 &lon=8.0 &keyattribute=postcode Response "errors":[], "warnings":[],

20 Geofencing Extension API Developer's Guide 20 User Guide } "requestid":"469b08f d3-912d-4adf81d6e93c", "geometries":[ "distance":655.66, "nearestlat":50.0, "nearestlon":8.0, "attributes": "POSTCODE":"2009", "ADMIN4":"Sydney",... } }, "distance": , "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.

21 Geofencing Extension API Developer's Guide 21 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.

22 Geofencing Extension API Developer's Guide 22 API Reference 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 Put Resource URI /layer_put.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 on page 13. 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 on page 13. 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.

23 Geofencing Extension API Developer's Guide 23 API Reference Response Elements / Attributes Parameter Type Mandatory Description errors List of elements with following Y Lists errors encountered during processing. If this list is not empty, then the application must not use the response content. attributes 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. 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. requestid string N If errors occurred during processing, then this id can be passed on to Technical Customer Support for further investigation. onerror boolean Y True, if errors occurred during processing and the result must not be used. Check Asset Position against Geo Fences Request Resource URI /check.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 on page 13. 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 on page 13. layer_id integer Y Check the position against all the geometries of this layer.

24 Geofencing Extension API Developer's Guide 24 API Reference Parameter Type Mandatory Description 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 Check the position against all the geometries of the comma separated list of layers. Either layer_id or layer_ids must be specified. Alternatively or in addition, maplayer or maplayers can be specified. 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. attributes string N Semicolon separated list of attribute names to be returned with the geometries. Default: Return all attributes. If all listed attributes are preceeded with a minus, then all attributes except those are returned. keyattribute string Y Name of the attribute that identifies each geometry. 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 :...

25 Geofencing Extension API Developer's Guide 25 API Reference } },... ], warnings : [ "...",... ], requestid : "...", geometries : [ distance :..., nearestlat :..., nearestlon :..., attributes : <attribute name 1> : "...", <attribute name 2> : "...",... }, geometry : "..." },... ], onerror :... Response Elements / Attributes Parameter Type Mandatory Description 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. 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. 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.

26 Geofencing Extension API Developer's Guide 26 API Reference Parameter Type Mandatory Description geometries. distance geometries. nearestlat geometries. nearestlon 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. float Y Latitude of the nearest point of the geometry/geometry border. Void if distance = -99,999,999. 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 Y Lists fence geometry attributes. attributes chosen in the request. 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 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 Bad Request Missing Parameters There was a unique key violation. Check data input. Required Parameters have not been provided. Duplicate entry [value] for key [field]

27 Geofencing Extension API Developer's Guide 27 API Reference Status Message Error (description) Details (example) Bad Request Invalid Incorrect authentication credentials given Authentication in the request. See Acquiring Credentials on page 13 for more information. 400 Bad Request Unable to complete request Diagnostic text. Further information about the cause of the error. Unauthorized User not "User does not have permission rights for authorized for export" or "User not authorized for this this action. action".