Geofencing Extension API

Transcription

1 Geofencing Extension API Developer's Guide Version 1.2

2 Geofencing Extension API Developer's Guide 2 Contents 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 Key Concepts...15 Examples...19 Example Submit Layer Example Check...20 Service Support Chapter 4: API Reference...22 Resources and Responses Layer List Request...23 Layer List Response Layer Upload Request...24 Layer Upload Response...25 Layer Put Request (Deprecated) Layer Put Response...26 Layer Delete Request...27

3 Geofencing Extension API Developer's Guide 3 Contents Layer Delete Response...27 Search Proximity Request...28 Search Proximity Response...29 Check Request (Deprecated)...31 Check Response Errors...34 Chapter 5: Coverage Information... 35

4 Geofencing Extension API Developer's Guide 4 Legal Notices Legal Notices 2016 HERE Global B.V. and its Affiliate(s). 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 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 Geofencing Extension API Developer's Guide 5 Document Information Document Information Product Name: Geofencing Extension API Version: Version 1.2 Document Name: Id: Status: Date: Signatory: Issuer-Certificate: Geofencing Extension API Developer's Guide 6f07a FINAL 2016-Mar-10, 9:50 (GMT) O=HERE, CN=here.com, ST=Berlin, C=DE O=HERE, CN=here.com, ST=Berlin, C=DE Serial-No.: method: urn:adobe.com:adobe.ppklite:adbe.pkcs7.sha1 (Adobe Signature)

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

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

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

11 Geofencing Extension API Developer's Guide 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: &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: &app_code=your_app_code} &layer_ids=123 &keyattribute=postcode

12 Geofencing Extension API Developer's Guide 12 Quick Start &proximity= , ,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 19

13 Geofencing Extension API Developer's Guide 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 Geofencing Extension API Developer's Guide 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 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 = 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 Geofencing Extension API Developer's Guide 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 Geofencing Extension API Developer's Guide 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: ADMIN_PLACE_ID CARTO_ID NLP_ZOOM_LEVEL WKT

17 Geofencing Extension API Developer's Guide 17 User Guide POLYGON (( , , , )) POLYGON (( , , )) 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 Geofencing Extension API Developer's Guide 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 Geofencing Extension API Developer's Guide 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 Geofencing Extension API Developer's Guide 20 User Guide -F " /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 &app_id=your_app_id} &app_code=your_app_code} &proximity=50.0,8.0,500 &keyattribute=postcode

21 Geofencing Extension API Developer's Guide 21 User Guide 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 Service Support If you need assistance with this or other HERE products, please contact your HERE representative or Technical Customer Support.

22 Geofencing Extension API Developer's Guide 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 Geofencing Extension API Developer's Guide 23 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 List Resource URI /layers/list.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. 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 layers Layer list Y List of all existing layer names for the given app_id.

24 Geofencing Extension API Developer's Guide 24 API Reference issues List of elements with following Y Lists issues encountered during processing. If this list is not empty, then the application must not use the response content. attributes 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. 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 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 Geofencing Extension API Developer's Guide 25 API Reference 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 List of elements with following Y Lists issues encountered during processing. If this list is not empty, then the application must not use the response content. attributes 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. Layer Put - DEPRECATED - Please use /search/ proximity instead! Resource URI /layer_put.json

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

27 Geofencing Extension API Developer's Guide 27 API Reference Layers Delete Resource URI /layers/delete.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. 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_ids list of integers Y Comma separated list of the slected layer ids. 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 layers Layer list Y List of the deleted layers. issues List of elements with following Y Lists issues encountered during processing. If this list is not empty, then the application must not use the response content. attributes 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.

28 Geofencing Extension API Developer's Guide 28 API Reference 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. Search Geometries close or including the given Coordinate Resource URI /search/proximity.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. 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_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. 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

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

30 Geofencing Extension API Developer's Guide 30 API Reference 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. 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 geometries. distance geometries. nearestlat geometries. nearestlon string Y The layer the geofoence geometry belongs to. 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.

31 Geofencing Extension API Developer's Guide 31 API Reference Check Asset Position against Geo Fences Request - DEPRECATED - Please use /search/proximity instead! Resource URI /check.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. 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 Geofencing Extension API Developer's Guide 32 API Reference 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 Geofencing Extension API Developer's Guide 33 API Reference Response Elements / Attributes 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. 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 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

34 Geofencing Extension API Developer's Guide 34 API Reference '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 Required Parameters have not been Parameters provided. Bad Request There was a Duplicate entry [value] for key [field] unique key violation. Check data input. Bad Request Invalid Incorrect authentication credentials given Authentication 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 "User does not have permission rights for authorized for export" or "User not authorized for this this action. action".

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