Network APIs Playground - Geofencing 0.3

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 Network APIs Playground - Geofencing API is a mocked version of the production-grade CAMARA - Geofencing API from CAMARA device location API family.

To use this API, subscribe to Network APIs Playground

This playground version provides responses for:

• predefined phone numbers associated with the unassigned country code +990 (e.g +99012345678)
• user-defined phone numbers added using the Network APIs Playground - Admin API

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 the Playground, 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/camara/playground/openidconnect/v1.0/token

        
        Copied 
      

In response, you will get an access_token.

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

        
        Copied 
      

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"
  }
}

        
        Copied 
      

Lab implementation specific:

Following fixed phone number can be used (or you can create new ones using the Network APIs Playground - Admin API):

request geofencing subscription creation (from MSISDN)

Request

curl -X POST "https://api.orange.com/camara/playground/api/geofencing/v0.3/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": "+99012345678"
      },
      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": "48.80",
          "longitude": "2.259"
        },
        "radius": 2000
      }
    },
    "initialEvent": true,
    "subscriptionMaxEvents": 10,
    "subscriptionExpireTime": "2024-03-22T05:40:58.469Z"
  }
}

        
        Copied 
      

Response

201 created
Content-Type: application/json

        
        Copied 
      

{
  "protocol": "HTTP",
  "sink": "https://endpoint.example.com/sink",
  "sinkCredential": {
    "credentialType": "PLAIN"
  },
  "types": [
    "string"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+99012345678"
      },
      "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"
}

        
        Copied 
      

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/playground/api/geofencing/v0.3/subscriptions"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

        
        Copied 
      

Response

200 OK
Content-Type: application/json

        
        Copied 
      

[{
  "protocol": "HTTP",
  "sink": "https://endpoint.example.com/sink",
  "sinkCredential": {
    "credentialType": "PLAIN"
  },
  "types": [
    "string"
  ],
  "config": {
    "subscriptionDetail": {
      "device": {
        "phoneNumber": "+99012345678"
      },
      "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"
]

        
        Copied 
      

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/playground/api/geofencing/v0.3/subscriptions/{subscriptionsId}"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

        
        Copied 
      

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/playground/api/geofencing/v0.3/subscriptions/{subscriptionsId}"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

        
        Copied 
      

Response

204 Event subscription deleted

        
        Copied 
      

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"
}

        
        Copied 
      

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"
}

        
        Copied 
      

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"
}

        
        Copied 
      

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: ..."
}

        
        Copied 
      

• 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: ..."
}

        
        Copied 
      

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": "+99012345678"
    },
    "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"
}

        
        Copied 
      

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": "+99012345678"
        },
        "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"
}

        
        Copied 
      

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Go up