Geofencing - CAMARA Sandbox - Orange lab 0.2 Beta

Getting started

• Getting started
• Disclaimer (sandboxed version)
• Introduction
• Using the API
  • Subscribe to the API
  • API Authentication
• API Description
  • Subscription management
    • Summary of resources
    • Summary of methods and URL
    • Summary of request body parameters
      • Definition of the webhook structure:
      • Definition of the subscription details structure:
      • Definition of the Device structure:
      • Definition of the area structure:
      • Definition of the center structure:
    • request geofencing subscription creation (from msisdn)
      • Request
      • Response
    • retrieve geofencing subscription list
      • Request
      • Response
    • retrieve one geofencing subscription from its id
      • Request
      • Response
    • delete one geofencing subscription
      • Request
      • Response
    • Most frequent errors
  • Notification
    • Notification structure:
      • data for area-entered and area-left notification
      • data for area-entered and subscription_ends notification
• Using Orange Geofencing simulator
• Looking for support ?
  • History of document

Disclaimer (sandboxed version)

This CAMARA Sandbox - Geofencing - Orange lab API is a sandboxed version of the production-grade CAMARA - Geofencing API from CAMARA device location API family.

It is running in our lab, against a small list of lab-specific mobile devices (see list of phone number available for test below).

This API could be suspended or upgraded any time without any notice.

Introduction

The CAMARA Geofencing API provides a standardized mechanism for managing geofencing notification subscription. As API consumer you will be able to subscribe to get notification when a given device is entering of leaving a given geographical area. During the subscription request, the consumer will provide the device identifier, the area definition (as a circle) and the URL where the notification will be posted.

Using the API

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

Note: In production environment the Geofencing API will require a 3-Legged OAuth 2.0 flow but as this implementation is provided on Orange Lab, the API works with a 2-Legged OAuth (OAuth 2.0 with Client Credentials grant type).

To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, you will use your Orange Developer Authorization header as authorization_header for the Basic authentication with Orange Developer.

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

In response, you will get an access_token.

{
       "token_type": "Bearer",
       "access_token": "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1Q.....ODSHIjf",
       "expires_in": "3600"
}

API Description

Subscription management

Summary of resources

This API has one resource subscriptions. The API allows to request subscriptions creation but also for a given API client to retrieve them and delete them.

Summary of methods and URL

Summary of subscriptions body parameters

Access Token extension schema:

Definition of the Config structure:

Following table provide details about config structure:

Definition of the subscriptionDetails structure:

Definition of the device structure:

Following table provide details about device:

Definition of the area structure:

Definition of the center structure:

Example of body request:

{
  "protocol": "HTTP",
  "sink": "https://notificationSendServer12.supertelco.com",
  "types": [
    "org.camaraproject.geofencing-subscriptions.v0.area-entered"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+33699901032"
      },
      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": "48.80",
          "longitude": "2.259"
        },
        "radius": 2000
      }
    },
    "initialEvent": true,
    "subscriptionMaxEvents": 10,
    "subscriptionExpireTime": "2024-03-22T05:40:58.469Z"
  }
}

Lab implementation specific:

We provide a simulated mode - please check the section “Using Orange Geofencing simulator” This simulated module get generated message from our network. It means that the Geofencing API service is a real one but as we could not have device moving around every time we generate fake network message listened from our CAMARA service.

request geofencing subscription creation (from MSISDN)

Request

curl -X POST "https://api.orange.com/camara/geofencing/orange-lab/v0/subscriptions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
  "protocol": "HTTP",
  "sink": "https://notificationSendServer12.supertelco.com",
  "types": [
    "org.camaraproject.geofencing-subscriptions.v0.area-entered"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+33699901032"
      },
      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": "48.80",
          "longitude": "2.259"
        },
        "radius": 2000
      }
    },
    "initialEvent": true,
    "subscriptionMaxEvents": 10,
    "subscriptionExpireTime": "2024-03-22T05:40:58.469Z"
  }
}

Response

201 created
Content-Type: application/json

{
  "protocol": "HTTP",
  "sink": "https://endpoint.example.com/sink",
  "sinkCredential": {
    "credentialType": "PLAIN"
  },
  "types": [
    "string"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+33699901032"
      },
      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": "48.80",
          "longitude": "2.259"
        },
        "radius": 2000
      }
    },
    "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
    "subscriptionMaxEvents": 5,
    "initialEvent": true
  },
  "id": "1119920371",
  "startsAt": "2024-07-11T19:08:47.612Z",
  "expiresAt": "2024-07-11T19:08:47.612Z",
  "status": "ACTIVE"
}

Go up

retrieve geofencing subscription list

All subscriptions created from the requesting client_id are provided. In the response, an array of subscriptions is provided. The complete representation of the subscription resource is provided (same structure as POST response)

Request

curl -X GET "https://api.orange.com/camara/geofencing/orange-lab/v0/subscriptions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

Response

200 OK
Content-Type: application/json

[{
  "protocol": "HTTP",
  "sink": "https://endpoint.example.com/sink",
  "sinkCredential": {
    "credentialType": "PLAIN"
  },
  "types": [
    "string"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+33699901032"
      },
      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": "48.80",
          "longitude": "2.259"
        },
        "radius": 2000
      }
    },
    "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
    "subscriptionMaxEvents": 5,
    "initialEvent": true
  },
  "id": "1119920371",
  "startsAt": "2024-07-11T19:08:47.612Z",
  "expiresAt": "2024-07-11T19:08:47.612Z",
  "status": "ACTIVE"
]

retrieve one geofencing subscription from its id

The subscription is retrieved only if it exists a subscription with this id for same client than the one requesting this GET operation.

In the response, a subscription is provided. The complete representation of the subscription resource is provided (same structure as POST response)

Request

curl -X GET "https://api.orange.com/camara/geofencing/orange-lab/v0/subscriptions/{subscriptionsId}"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

Response

The complete representation of the subscription resource is provided (same structure that POST response)

delete one geofencing subscription

The subscription is deleted only if it exists a subscription with this id for same client than the one requesting this DELETE operation.

Request

curl -X DELETE "https://api.orange.com/camara/geofencing/orange-lab/v0/subscriptions/{subscriptionsId}"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

Response

204 Event subscription deleted

Most frequent errors

If invalid input are provided in POST /subscriptions, in particular for the device identifier, a 400 error is triggered.

HTTP/1.1 400 Invalid input
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Invalid input"
}

If the consumer request for a non existing subscription in GET /subscriptions/{subscriptionsId}, a 404 error is sent.

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found"
}

If the subscription service is down, a 503 error is sent.

HTTP/1.1 503 Service unavailable
Content-Type: application/json
{
  "code": "UNAVAILABLE",
  "status": 503,
  "message": "Service unavailable"
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

• Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": "UNAUTHENTICATED",
  "status": 401,
  "message": "Authorization failed: ..."
}

• Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}

Notification

Notifications will be received at consumer side, on the URL provided in the subscriptions.notificationUrl field in the subscription request (see above).

The API contains also the Notification definition in the callbacks part. The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.

Following event types are managed for this API:

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

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

Note: Additionally to these list, org.camaraproject.geofencing.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 (required by the requester) has been reached or if the API server has to stop sending notification prematurely.

Notification structure:

Following table describes the notification structure:

data for area-entered and area-left notification

The subscription area-entered or area-left notification data structure is the following:

Example of notification received:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "id": "6a11dad7-64b3-4f12-a28f-8a24411fe8e0",
  "source": "com.orange.camara.geofencing",
  "type": "org.camaraproject.geofencing.v0.area-entered",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "data": {
    "device": {
      "phoneNumber": "+33699901032"
    },
    "area": {
      "areaType": "CIRCLE",
      "center": {
        "latitude": 48.8,
        "longitude": 2.29
      },
      "radius": 2000
    },
    "subscriptionId": "5c9b3fa2-6d65-4768-ba52-a7281a525789"
  },
  "time": "2024-01-16T15:37:04.052088556Z"
}

data for area-entered and subscription_ends notification

The subscription ends notification data structure is the following:

Example of notification received:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
    "id": "9f625ec0-f8d6-4ef2-a1ee-62a0424b4cc9",
    "source": "com.orange.camara.geofencing",
    "type": "org.camaraproject.geofencing.v0.subscription-ends",
    "specversion": "1.0",
    "datacontenttype": "application/json",
    "data": {
        "device": {
            "phoneNumber": "+33699901032"
        },
        "terminationReason": "SUBSCRIPTION_EXPIRED",
        "area": {
            "areaType": "CIRCLE",
            "center": {
                "latitude": 48.8,
                "longitude": 2.29
            },
            "radius": 2000
        },
        "subscriptionId": "19fbaf8d-0b76-4fde-a8d1-5991613e2ab1"
    },
    "time": "2024-01-16T15:26:29.388137893Z"
}

Using Orange Geofencing simulator

Getting notifications from real life network will require that our lab mobile devices are always moving... which is not easy to achieve.

In order to allow developers to make tests, we have created a network event simulator that sends network notifications to our Geofencing API code. With this simulator, you have to use the phone numbers and the geographic areas listed below.

To use this simulator, you need to add /simulated as suffix in the API path for the POST. So, in order to request a subscription with a simulator, you have to use the following: POST https://api.orange.com/camara/geofencing/orange-lab/v0/subscriptions/simulated. No need to add /simulated for GET and DELETE operations.

Following phone number must be used (other will not work):

For 33699901031 and 33699901032 we switch in sequence between this 4 cells:

Reminder: in the subscription minimum radius is 2000 meters so you have to define monitored accordingly.

Hints: For Vanves, monitoring 48.816, 2.305 with a 2000 meters radius, for Clamart (48.79, 2.265,2000) and for Bagneux (48.785, 2.305,2000) work very well ;)

For 33699901033 to 33699901040 we switch randomly between 15 cells:

Note: Each subscription is limited to 25 notifications.

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Go up