Service Localisation API

location API

Here, you'll find all of the technical documentation and SDKs you need to enable you to start developing with the API.

We've tried to make it easy for you, by breaking the information down into clear areas:
before getting started, getting started and advanced development.

Localisation API

before getting started
getting started
advanced development

before getting started

Before getting started, please read the information below.

You'll then be ready to move onto the 'getting started' section.

general information

pre-requisite conditions

API service interactions

reminders on XML-RPC

general information

The Location API from Orange provides customers of the Orange business platform the ability to locate mobile numbers belonging to a company Closed User Group (CUG).

The API uses Cell-ID technology that gives the co-ordinates of the cell to which the mobile is attached.

The accuracy of the location depends on the density of the Orange GSM/GPRS network.

For information, the level of accuracy reaches about 100-500m in built-up areas and 5-10km in the countryside.

A few things to note:

The shape of the cell depends of the topology of the land (obstacles, height of mobile phone base station), the power and emission angle. To provide a datum that can be used simply, the shape of the cell has been schematised by a circle for which the API provides the radius (in metres) and the barycentre.

For bi-directional masts (for example, on motorways), the shapes of the two cells will be very long. It is possible that the mobile falls outside the provisional zone.

Also, the radius information provided by the API is given for information purposes and is not contractually binding.

pre-requisite conditions

The following conditions must be met before deployment of your application:

the customer must have subscribed to an Enterprise location service and filled up a form to deliver to the CNIL
each mobile user must have signed a consent form (to be kept by the customer) and authorised the use of his location information
each mobile device must be registered in a closed user group set out by the customer the service is intended for.
mobile devices must include an Orange France SIM card.
mobile devices must be under coverage of the Orange France network.
mobile devices must be switched on

More information about the above can be found in the develop area once you become a premium member.

API service interactions

This Location API is available as a Web XML-RPC service.

Authentication is based on Basic HTTP (see RFC 2617).
The confidentiality and integrity of the data are guaranteed by the HTTPS (secure HTTP) protocol that secures all information on the network to access the service.

You can find out more about the XML-RPC in the next section.

reminders on XML-RPC

what is XML-RPC?

XML-RPC is above all a specification and implementations that enable software applications running on different systems to run procedures (RPC) across and Internet-type network.

This procedure specification uses the HTTP protocol for transporting and an XML instance for encoding. XML-RPC was designed to be as simple as possible also enabling complex data structures to be sent, processed and returned.

the XML-RPC community

The XML-RPC is extremely active as a list of available implementations shows. A variety of implementations for open source or commercially-available operating systems, programming languages are available.

requirements for using the Location API

Before being able to use a weblog reservation service, a certain number of requirements should be checked.

The XML-RPC implementation chosen must enable:
The use of SSL for HTTP queries
A user ID/password combination through a Basic Authentication mechanism.

XML-RPC implementations

The XML-RPC implementations satisfied the criteria set out above:

Java	: The implementation used is that developed by Apache (http://xml.apache.org/)
Perl	: XML-RPC module (http://www.blackperl.com/RPC::XML/)
PHP	: phpxmlprc extension (http://phpxmlrpc.sourceforge.net/)
.NET	: XML-RPC.NET open library (http://www.xml-rpc.net/).

This list is not exhaustive and not a reference.
For further details, see http://www.xmlrpc.org/.

getting started

Now you've read the 'before getting started' section, we'll take you through some sample codes.

Java source code
PHP source code
C# source code

Java source code

The implementation used is that developed by Apache (http://xml.apache.org/) Note that the SSL package requires additional JSSE classes if used with a JDK1.3. No additional classes are required for JDK1.4 or higher. For further information, see the Resources chapter in the Advanced Development Guide.

LocationClient.java

import java.util.Hashtable;
import java.util.Vector;
import org.apache.xmlrpc.XmlRpcClient;
public class LocationClient
{
   /**Constructor for the LocationClient object */ 
   public LocationClient()
   {
   super();
   }
   public void sendRequest() throws Exception
   {
   // Identifier for the positioning service
 String username="MyUserName"; // example : LOCxxxxxxxx208-01
   // Password for the positioning service
 String password = "MyPassword";
 String application = "MyApplication"; // informative
   // List of mobiles to locate
 Vector msisdns = new Vector();
   // Attention, the MSISDN format is E164 (international)
   // Location of the mobile 336xxxxxxxx corresponds 06xxxxxxxx in France
 msisdns.add("336xxxxxxxx");
   // XML-RPC positioning server URL
 String server_url = "https://api.orangemib.net/location/xmlrpc/service";
   // Name of the localisation method
 String method_name = "location.locate";
 Vector parameters = new Vector();
 parameters.add(username);
 parameters.add(application);
 Hashtable requestInfo = new Hashtable();
 requestInfo.put("geodeticDatum","WGS-84");
 requestInfo.put("coordinateSystem","LL");
 requestInfo.put("positionFormat","DMS0");
//management of the cell shape
//v1.3
requestInfo.put("shape",new Boolean(true));
//v1.3
 parameters.add(requestInfo);
 parameters.add(msisdns);
// Creation of the server object
 XmlRpcClient xmlRpcClient = new XmlRpcClient(server_url);
 xmlRpcClient.setBasicAuthentication(username, password);
// Call the method
 Object result = xmlRpcClient.execute(method_name, parameters);
 Hashtable positions = (Hashtable)result;
 System.out.println("Submitted items " + positions.get("submittedCount"));
 System.out.println("Accepted items " + positions.get("acceptedCount"));
 System.out.println("Operation time " + positions.get("operationTime"));
 System.out.println("Items");
 Vector items = (Vector)positions.get("items");
 for(int i=0;i <items.size();i++){
  Hashtable item = (Hashtable) items.get(i);
  System.out.println("\tItem " +i);
  System.out.println("\tMSISDN " +item.get("msisdn"));
  System.out.println("\tPosition Time " +item.get("positionTime"));
  System.out.println("\tResult Code " +item.get("resultCode"));
  System.out.println("\tResult Description " +item.get("resultDescription"));
  System.out.println("\tType " +item.get("type"));
  if (item.get("type")!=null){
  Hashtable point = (Hashtable) item.get("point");
  Hashtable latitude = (Hashtable) point.get("ll_latitude");
  Hashtable longitude = (Hashtable) point.get("ll_longitude");
//management of the cell shape
//v1.3
             Hashtable shape = (Hashtable) item.get("shape");
//v1.3 : management of the cell shape
  System.out.println("\tLatitude " +latitude.get("direction") 
+ " "+latitude.get("degrees")+"'"+latitude.get("minutes")
+ "'"+latitude.get("seconds")+"\"");
  System.out.println("\tLongitude " +longitude.get("direction")
+ " "+longitude.get("degrees")+"'"+longitude.get("minutes")
+ "'"+longitude.get("seconds")+"\"");
//management of the cell shape
//v1.3
                 System.out.println("\tRayon " +shape.get("radius"));
                 System.out.println("\tStartAngle " +shape.get("start_angle"));
                 System.out.println("\tEndAngle " +shape.get("end_angle"));
                 System.out.println("\tName " +shape.get("name"));
//v1.3
  }
 }
   }
    /**
 * LocationClient main class programme
 *
 */
   public static void main(String[] args) throws Exception
   {
// If you use a proxy, please complete the 2 lines below:
// and replace "nom_proxy" and "port_proxy" with the name of the proxy 
// and its port
   //System.setProperty("https.proxyHost", "nom_proxy");
   //System.setProperty("https.proxyPort","port_proxy");
   LocationClient client = new LocationClient();
   client.sendRequest();
   }
}

PHP source code

The implementation used is based on the phpxmlprc extension (http://phpxmlrpc.sourceforge.net/). Note that the SSL package requires the "curl" module. Its availability in the distribution remains to be verified.

LocationClient.php

<?php
include("xmlrpc/xmlrpc.inc");
// Identifier for the positioning service
$username = "MyUserName";   // exemple : LOCxxxxxxxx208-01
// Password for the positioning service
$password = "MyPassword";
$application = "MyApplication";
// List of mobiles to locate
$phones = new xmlrpcval(array(
 new xmlrpcval("336xxxxxxxx")
), "array");    // corresponds to the mobile n° 06xxxxxxxx in France
// XML-RPC positioning server URL
$server_hostname = "api.orangemib.net";
$server_path = "/location/xmlrpc/service";
$server_port = 443;
// Name of the localisation method
$method_name = "location.locate";
$client = new xmlrpc_client ($server_path, $server_hostname, $server_port);
$client->setCredentials($username, $password);
$client->setSSLVerifyPeer(false);
$client->setSSLVerifyHost(false);
$req = new xmlrpcmsg($method_name);
$req -> addParam(new xmlrpcval($username));
$req -> addParam(new xmlrpcval($application));
$geodesic = new xmlrpcval(array(
 "geodeticDatum" => new xmlrpcval("WGS-84"),
 "coordinateSystem" => new xmlrpcval("LL"),
 "positionFormat" => new xmlrpcval("DMS0")), "struct"); 
$req -> addParam($geodesic);
$req -> addParam($phones);
print $req->serialize();
$res = $client->send($req, 30, "https");
$value = $res->value();
print $value;
if (!$res->faultCode()) {
    print "Response\n";
    print $res->serialize();
} else {
    print "Fault\n";
    print "Code: " . $res->faultCode() . "\n";
    print " Reason '" .$res->faultString()."'\n";
}
?>

C# source code

The code uses the XML-RPC.NET open library (http://www.xml-rpc.net/). The 'CookComputing.XmlRpcV2.dll' library should be added to your project in reference in the case of C# 2 or 'CookComputing.XmlRpc.dll' for C# 1.

using System;
using System.Collections;
using CookComputing.XmlRpc;
namespace Localisation
{
   class Localisation_Sample
   {
      // Definition of the LocationRequestInfo structure
      public struct LocationRequestInfo
      {
         public string geodeticDatum;
         public string coordinateSystem;
         public string positionFormat;
         public bool shape;
      }
      // Definition of the XML-RPC 'location.locate' method
      [XmlRpcUrl("https://api.orangemib.net/location/xmlrpc/service")]
      public interface ILocalisation : IXmlRpcProxy
      {
         [XmlRpcMethod("location.locate")]
         XmlRpcStruct GetLocalisation(
            string enterpriseLogin, 
            string applicationName, 
            LocationRequestInfo requestInfo, 
            string[] msisdns);
      }
      [STAThread]
      static void Main(string[] args)
      {
         // Définition of the login/password, application's name and MSISDNs
         string login = "MyLogin";
         string motdepasse = "MyPassword";
         string applicationName = "LocalisationTest";
         string[] msisdns = new string[]{"336XXXXXXXXX"};
         // Defintion of the type of query
         LocationRequestInfo requestinfo;
         requestinfo.geodeticDatum = "WGS-84";
         requestinfo.coordinateSystem = "LL";
         requestinfo.positionFormat = "DMS0";
         //management of the cell shape
         //v1.3
         requestinfo.shape = true;
         //v1.3
         // Instantiate a proxy
         Localisation proxy =
             (ILocalisation)XmlRpcProxyGen.Create(typeof(ILocalisation));
         // The timestamp sent by Orange is not standard for the library
         // It must be authorised
         proxy.NonStandard = XmlRpcNonStandard.AllowNonStandardDateTime;
         // The authentication goes into the message header
         byte[] credentialBuffer = 
            new System.Text.UTF8Encoding().GetBytes(login + ":" + password);
         proxy.Headers.Add("Authorization", "Basic " + 
            Convert.ToBase64String(credentialBuffer)); 
         // The XML-RPC method is called
         XmlRpcStruct result = 
            proxy.GetLocalisation(login, applicationName, requestinfo, msisdns);
         
         // Display coordinates
         Console.WriteLine("Submitted items " + result["submittedCount"]);
         Console.WriteLine("Accepted items " + result["acceptedCount"]);
         Console.WriteLine("Operation time " + result["operationTime"]);
         Console.WriteLine("Items ");
         Array items = (Array)result["items"];
         for (int i=0; i<items.Length; i++)
         {
            XmlRpcStruct item = (XmlRpcStruct)items.GetValue(i);
            Console.WriteLine("\tItem " + i);
            Console.WriteLine("\tMSISDN " + item["msisdn"]);
            Console.WriteLine("\tPosition Time " + item["positionTime"]);
            Console.WriteLine("\tResult Code " + item["resultCode"]);
            Console.WriteLine("\tResult Description " + item["resultDescription"]);
            Console.WriteLine("\tType " + item["type"]);
            if ((string)item["type"] == "LL")
            {
               XmlRpcStruct point = (XmlRpcStruct)item["point"];
               XmlRpcStruct latitude = (XmlRpcStruct)point["ll_latitude"];
               XmlRpcStruct longitude = (XmlRpcStruct)point["ll_longitude"];
               //management of the cell shape
               //v1.3
               XmlRpcStruct shape = (XmlRpcStruct)item["shape"];
               //v1.3
               Console.WriteLine("\tLatitude " + latitude["direction"] +" "
+ latitude["degrees"]+"'"+ latitude["minutes"]+"'"+ latitude["seconds"]+"\"");
               Console.WriteLine("\tLongitude " + longitude["direction"]+" "
+ longitude["degrees"]+"'"+ longitude["minutes"]+"'"+ longitude["seconds"]+"\"");
               //management of the cell shape
               //v1.3
               Console.WriteLine("\tRayon " + shape["radius"]);
               Console.WriteLine("\tStartAngle " + shape["start_angle"]);
               Console.WriteLine("\tEndAngle " + shape["end_angle"]);
               Console.WriteLine("\tName " + shape["name"]);
               //v1.3
            }
         }         
      }
   }
}

advanced development

If you're an intermediate or advanced developer and managed to whizz through the 'getting started' area, then this section is where you can find everything to satisfy your advanced development needs.

download the Location API advanced development manual