.wpb_animate_when_almost_visible { opacity: 1; }

Device Location Verification - CAMARA Sandbox - Orange lab 0.1 Beta

Implement precise location-based services by confirming if a device is within a specified geographical area

Use this API Contact us

Getting started



Disclaimer (sandboxed version)

This CAMARA Sandbox - Device Location Verification - Orange lab API is a sandboxed version of the production-grade CAMARA - Device Location Verification 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 Verification API provides a standardized mechanism for checking mobile equipment geographic location. API customers are able to verify whether the location of certain user device is within the area specified by the provided coordinates (latitude and longitude) and some expected accuracy. The API response is a boolean: The equipment is within (or not) the accuracy radius with a center point at provided latitude/longitude.

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 Device Location Verification 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 with client credentials).

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 verify. verificationResult attribute provides in the response information about mobile equipment location check.

Summary of methods and URL

Use case of operationURL method
I want to check location of a device from a MSISDN number, an external identifier or an IP (+port)POST "https://api.orange.com/camara/location-verification/orange-lab/v0/verify"

Summary of request body parameters

NameDescriptionTypeMandatory
deviceAn object with four fields, each of them make possible to pass device identifier in different format: networkAccessIdentifier, phoneNumber, ipv4Address and ipv6AddressSee below information on deviceYes
areaUsed to define the geographical area to be verified.See below information on areaYes
maxAgeMaximum age of the location information which is accepted for the location retrieval (in seconds).integerNo

Note on maxAge:

  • Absence of maxAge means "any age" is acceptable for the client. In other words, this is like maxAge=infinite. The system still return lastLocationTime in the response. If the system is not able to provide location a error 404 with code LOCATION_RETRIEVAL.DEVICE_NOT_FOUND is send back.
  • maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide fresh location an error 422 with code LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE is send back.
Definition of the area structure:
NameDescriptionTypeMandatory
areaTypeType of this area. Only CIRCLE value is managedstringYes
centerStructure to define circle center coordinatesSee below information on centerYes
radiusAccuracy expected for location verification in meters. Must between 2 000 and 200 000.numberYes
Definition of the center structure:
NameDescriptionTypeMandatory
latitudeLatitude component of location. Must between -90 and 90.numberYes
longitudeLongitude component of location. Must be between -180 and 180.numberYes

Lab implementation specific:

As this implementation works on our lab and the devices are located there, if you expect a positive result you should verify with following area center:

  • latitude: 48.800176,
  • longitude : 2.29
User equipment identifier

Following table provide details about device :

NameTypeFormat
networkAccessIdentifierstringExternal Identifier format of the GPSI
phoneNumberstringSubscriber number in E.164 format (starting with country code). Mandatory prefixed with '+'
Ipv4AddressstringIPv4 address may be specified in form <address/mask>. If address we expect an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. If address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
Ipv6AddressstringIPv6 address, following IETF 5952 format, may be specified in form <address/mask>. If address, the /128 subnet is optional for single address (2001:db8:85a3:8d3:1319:8a2e:370:7344 or 2001:db8:85a3:8d3:1319:8a2e:370:7344/128). If address/mask, an IP v6 number with a mask (2001:db8:85a3:8d3::0/64 or 2001:db8:85a3:8d3::/64 )

Lab implementation specific:

Only requests using phoneNumber are operational. Following phone number must be used (other will not work):

Phone Number
33699901031
33699901032
33699901033
33699901034
33699901035
33699901036
33699901037
33699901038
33699901039
33699901040

Go up

Example of body query

{
"device": {
    "phoneNumber": "+33699901031"
},
"area": {
  "areaType": "CIRCLE",
    "center": {
      "latitude": 48.80,
      "longitude" : 2.26999
    },
  "radius" : 2000},
"maxAge": 3600
}

check mobile equipment location (from msisdn)

Request
curl -X POST "https://api.orange.com/camara/location-verification/orange-lab/v0/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"device": {
    "phoneNumber": "+33699901031"
},
"area": {
  "areaType": "CIRCLE",
    "center": {
      "latitude": 48.80,
      "longitude" : 2.26999
    },
  "radius" : 2000},
"maxAge": 3600
}
Response
200 Location verification successful
Content-Type: application/json
{
  "lastLocationTime": "2024-01-05T14:28:46.699450286Z",
  "verificationResult": "TRUE"
}

Go up

Fields description

The API response attributes are described in this table:

NameDescriptionTypeMandatory
lastLocationTimelast location time of the device from the network. Will be between [the time of the request] and [the time of the request + maxAge]string (date-time)Yes
verificationResultIf TRUE the mobile equipment is within the circle with radius=accuracy and circle center=latitude, longitude.
If FALSE the mobile is not in this zone.
If PARTIAL the mobile could be within the zone - in this case a matchRate is send also.
If UNKNOWN the network cannot locate the device
numberYes
matchRateEstimation of the match rate between the area in the request (R), and area where the network locates the device (N), calculated as the percent value of the intersection of both areas divided by the network area, that is (R ∩ N) / N * 100. Included only if VerificationResult is PARTIALintegerNo

The following diagram illustrates verificationResult and matchRate:

enter image description here

Note:

  • If the network is not able to localize the equipment within the max age requested, status 404 is sent.
  • If the localisation service is not live and running error 503 is sent

Go up

Most frequent errors

If invalid input are provided in particular for the ueId 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": "Location outdated"
}

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

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Version of the documentmodification datedescription of modifications
1.027/11/2023initialization by Orange CAMARA APIs team
1.105/01/2024Add MatchRate and lastLocationTime in response
rename UeId to device and align structure
Introduce new area definition
1.207/06/2024Slight change on maxAge management
1.320/08/2024Indicate that the prefix '+' is mandatory for the phoneNumber

Go up