Getting started

• Introduction
  • Subscribe to the API
  • API Authentication
  • API Description
    • Summary of resources
    • Summary of methods and URL
    • Summary of request body parameters
    • check mobile equipement location (from msisdn)
      • Request
      • Response
      • Fields description
    • Most frequent errors
  • History of document

Introduction

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}}" \
https://api.orange.com/openidconnect/fr/v1/authorize

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:

http://www.myserver.com/?code=OFR-908cb0277a7e3d358c39d0792750875e...f4139a840cdcb6e&state=upToYouData&scope=device-location-read

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}" 
https://api.orange.com/openidconnect/fr/v1/token 

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

Go up

Summary of request body parameters

Following table provide details about ueId:

Go up

check mobile equipement location (from msisdn)

Request

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
}

Response

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
{
  "code": "INVALID_ARGUMENT",
  "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
{
  "code": "INVALID_ARGUMENT",
  "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
{
  "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: ..."
}

Go up

History of document

Go up