Introduction

With this API, API consumers can create subscriptions for their devices to receive notifications when a device enters or exits a specified area.

The area provided in the request is described by a circle determined by coordinates (latitude and longitude) and an accuracy defined by the radius.

Upon successfully creating a subscription, the API will provide an Event Subscription ID, and it will indicate the subscription's expiration date.

If the geofencing-state of a device changes, the event subscriber will be notified back to the provided Notification-Url given by the subscription-request.

Device geofencing API could be useful in scenarios such as:

• Tracking devices for Presetting of Home-Settings
• Tracking of logistics

Relevant terms and definitions

• Device: A device refers to any physical entity that can connect to a network and participate in network communication.

• Area: It specifies the geographical surface which a device is planned to enter or exit.

API Functionality

The API exposes following capabilities:

Device Geofencing subscription

These endpoints allow to manage event subscription on geofencing device location event.

The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.

It is mandatory in the subscription to provide the event type for which the client would like to subscribe.

Following event types are managed for this API:

• org.camaraproject.geofencing-subscriptions.v0.area-entered - Event triggered when the device enters the given area

• org.camaraproject.geofencing-subscriptions.v0.area-left - Event triggered when the device leaves the given area

Note: Additionally to these list, org.camaraproject.geofencing-subscriptions.v0.subscription-ends notification type is sent when the subscription ends. This notification does not require dedicated subscription.

It is used when:

• the subscription expire time (optionally set by the requester) has been reached
• the maximum number of subscription events (optionally set by the requester) has been reached
• the subscription was deleted by the requester
• the Access Token sinkCredential (optionally set by the requester) expiration time has been reached
• the API server has to stop sending notification prematurely
• the specified geofence-area cannot be covered or is too small to be managed

Notification callback

This endpoint describes the event notification received on subscription listener side when the event occurred. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.

WARNING: This callback endpoint must be exposed on the consumer side as POST /{$request.body#/sink}. Developers may provide a callback URL on which notifications regarding geofencing can be received from the service provider. If an event occurs the application will send events to the provided webhook - 'sink'.

Authorization and authentication

The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.

Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

Further info and support

(FAQs will be added in a later version of the documentation)