Disclaimer (sandboxed version)

This CAMARA Sandbox - Device Location Retrieval - Orange lab API is a sandboxed version of the production-grade CAMARA - Device Location Retrieval API.

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 Device Location Retrieval API provides a standardized mechanism for retrieving mobile equipment geographic location. API customers are able to retrieve the location of a specified user device. It can provide the location according to different area types. As of now only CIRCLE representation is provided.

For “CIRCLE” area type, the center of the circle (latitude and longitude) as well as the accuracy radius will be provided in the response.

Subscribe to the API

You get the Authorization header credentials when you register your application on the [Orange Developer Console] (https://developer.orange.com/myapps).

API Authentication
Note: In production environment the Device Location Retrieval 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.

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": "66AeYJF8eJQ...2SjkFg9LB1LePC",
       "expires_in": "3600"
}

API Description

Summary of resources
This API has one resource retrieve. RetrievalResult attribute provides in the response information about mobile equipment location check.

Summary of methods and URL

Summary of request body parameters

Following table provide details about device:

Lab implementation specific:

Only requests using phoneNumber are operational.

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

33699901031
33699901032
33699901033
33699901034
33699901035
33699901036
33699901037
33699901038
33699901039
33699901040

Summary of response parameters

Retrieve mobile equipement location (from msisdn)
Request

curl -X POST "https://api.orange.com/camara/location-retrieval/orange-lab/v0/retrieve"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  {
"device": {
    "phoneNumber": "33699901031"
},
"maxAge": 60
}

Response

200 Location retrieval successful
Content-Type: application/json

{
  "lastLocationTime": "2023-01-17T13:18:23.682Z",
  "area": {
    "areaType": "CIRCLE",
    "center": {
      "latitude": 50.735851,
      "longitude": 7.10066
    },
    "radius": 2000
  }
}

Fields description
The response features “area” and “lastLocationTime” attributes with the location area where the device was located.

Note:

If the network is not able to localize the equipment, error code 404 is sent.
If the service is not up and running, error code 503 is sent
if the maxAge threshold cannot be satisfied, error code 400 is sent.
Go up

Most frequent errors
If invalid input are provided 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 network back end is not able to localize the equipment, a 404 error is sent.

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Unknown Location"
}

If the localisation service is not up and running, 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: ..."
}