.wpb_animate_when_almost_visible { opacity: 1; }
CAMARA - Device Location Beta
The Device Location API provides programmable interface for developers to verify the location of a device.

Getting started


The CAMARA Device Location 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 equipement 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

HTTPS requests to the REST API are protected with 3-Legged OAuth 2.0 flow. To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, you will first use your Orange Developer Authorization header as authorization_header to request the OAuth authorization code from the user for the scope device-location-read.

curl -X GET \
-H "Authorization: {{ authorization_header }}" \
-d "scope=device-location-read" \
-d "redirect_uri={{your_application_callback}}" \
-d "response-type=code" \
-d "state={{your_state}}" \

Once receiving this request, the Orange server displays a web page that takes care of authenticating the user. The end-user will be asked to give his/her consent for using the service.

Once this is done, the redirect URL is automatically called back with the following query-string parameters:

  • code: the authorization code you will use with the token endpoint.
  • state : the value you gave when calling the Authorize endpoint (i.e. state query-string parameter).
  • scope : the scope is set in case the required scope is not entirely authorized. It then contains the actual authorized scope (which thus is a subset of the requested scope). For this api only scope device-location-read is managed.

As an example:


You can now exchange the obtained code (OFR-908cb0277a7e3d358c39d0792750875e…f4139a840cdcb6e in the example) to get OAuth 2.0 tokens. This token is mandatory for API calls to protected resources. To get these tokens, a POST request must be sent to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format:

  • authorization_header (required): the credentials of your client application (i.e. client_id/client_secret)
  • grant_type (required): fixed to authorization_code
  • code (required): the code you received in the callback request (i.e. code query-string parameter) after calling the Authorization endpoint.
  • redirect_uri (required): the same callback URL you provided for the Authorization request.

As an example:

curl -X POST 
-H "Authorization: {authorization_header}" 
-d "grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}" 

On success, the HTTP response status will be set to 200 OK, and the body will be a JSON object containing the access_token to be used with each of your API calls. The access_token is valid for the duration, in seconds, specified by expires_in. At the present time, access_token has a lifetime of 1 hour.

Go up

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/location/v0/verify

Go up

Summary of request body parameters

ueIdAn object with four fields, each of them make possible to pass ueId in different format: externalId , msisdn, ipv4Addr and ipv6AddrSee below information on ueIdYes
uePortIf a public ipv4Addr is provided for the ueId object, the port allocated to the UE must also be specifiedstringNo
latitudeLatitude component of location. Must between -90 and 90.numberYes
longitudeLongitude component of location. Must be between -180 and 180.numberYes
accuracyAccuracy expected for location verification in km. Must between 2 and 200.numberYes

Following table provide details about ueId:

externalIdstringExternal Identifier format of the GPSI
msisdnstringSubscriber number in E.164 format (starting with country code). Optionally prefixed with '+'
Ipv4AddrstringIPv4 address may be specified in form <address/mask>. If address we expect an IPv4 number in dotted-quad form 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
Ipv6AddrstringIPv6 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 )

Go up

check mobile equipement location (from msisdn)

curl -X POST "https://api.orange.com/location/v0/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"ueId": {
    "msisdn": "41793834315"
"latitude": 50.735851,
"longitude" : 7.10066,
"accuracy" : 2
200 Location verification successful
Content-Type: application/json
  "verificationResult": true

Go up

Fields description

The response only feature verificationResult attribute. Set to true, the mobile equipment is within the circle with radius=accuracy and circle center=latitude, longitude. Set to false the mobile is not in this zone.

Note: If the network is not able to localize the equipement, status 503 is sent.

Go up

Most frequent errors

If invalid input are provided in particularfor the ueId a 400 error is triggered.

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

If the network back end is not able to localize the equipment, a 503 error is sent.

HTTP/1.1 503 Service unavailable
Content-Type: application/json
  "status": 400,
  "message": "Invalid input"

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
  "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
  "status": 403,
  "message": "Operation not allowed: ..."

Go up

History of document

Version of the documentmodification datedescription of modifications
1.016/1/2023initialization by Orange CAMARA APIs team

Go up