Device Geofencing Subscriptions wip
OAS 3.0
https://developer.orange.com/ope-contents/channels/87afd7365baec589/offers/TzBqH27lNS6992Iz/products/bUG1mlFh34vN2eWo/contents/swagger/vs6wKKA7Dwq1nLzY/geofencing-od.yamlAPI to create, retrieve and delete event subscriptions to realize geofencing for a user device.
Introduction
With this API, customers 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 type
are managed for this API:
org.camaraproject.geofencing-subscriptions.v0.area-entered
- Event triggered when the device enters the given areaorg.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 Access Token
sinkCredential
(optionally set by the requester) expiration time has been reached - the API server has to stop sending notification prematurely
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'.
Further info and support
(FAQs will be added in a later version of the documentation)
https://api.orange.com/camara/geofencing/orange-lab/v0
Server variables
apiRoot |
Geofencing subscriptionsOperations to manage event subscription on geofencing events for leaving and entering an area
Operations to manage event subscription on geofencing events for leaving and entering an area