LBS API


This allows to send and receive location requests using a REST based API to find the location of users and create rich & real-time applications. The Request Service of this API enables the Service Provider application to request location of a particular mobile number and Idea Pro sends the location as a response.

E.g.  A third party application requesting a location of a particular MSISDN (mobile phone) through LBS API and receiving the response with the location of the requested MSISDN (mobile phone).

Method

POST

 

Get Location

Get Location service comprises of location request and location response. Location request URL for Get Location service is as follows:

Simulator:
http://localhost:7000/lbs/locate
Active production:
https://api.dialog.lk/lbs/locate

 

Request

Following is a sample LBS request with mandatory and optional parameters.


{
  "applicationId": "APP_001768",
  "password": "729fdf8ea178cdea9857eeb9a059fd6e",
  "subscriberId": "tel:94771234567",
  "serviceType": "IMMEDIATE",
  "responseTime": "NO_DELAY",
  "freshness":  "HIGH",
  "horizontalAccuracy": "1500",
  "vesrion": "2.0"
}

 

Following parameters need to appear in the LBS request as mandatory parameters.

  • applicationId
  • password
  • subscriberId
  • serviceType

 

Following is a sample LBS Request with mandatory parameters.


{
  "applicationId": "APP_001764",
  "password": "39ca9208fbb1171f027e8d24fe5e275e",
  "subscriberId": "tel:94771234567",
  "serviceType": "IMMEDIATE"
}

 

Following are the Request parameters of LBS.

 

Parameter Name Description Type Mandatory / Optional
applicationId Application ID as given when provisioned String Mandatory
password Password given when provisioned String Mandatory
version API version shall be numbered as 1.0, 2.0 etc String Optional
If not specified shall be validated against the latest version
subscriberId MSISDN of the subscriber for which the location update is needed. This is a unique identifier.
Note: MSISDN might be a masked number depending on the type of the application
String Mandatory
Only a single value can be sent per request
serviceType Required MLP service type.
Currently supports; IMMEDIATE
ENUM Mandatory
responseTime QoS parameter defines the accepted delay for the response.Accepted values and precedence is as below;

  1. NO_DELAY
  2. LOW_DELAY
  3. DELAY_TOLERANCE

 

NO_DELAY has the highest precedence.

 

Eg: Third party application can not initiate location requests with NO_DELAY if the provisioned value is ‘LOW DELAY’.

 

But can initiate location requests with LOW_DELAY and DELAY_TOLERENCE.

ENUM Optional
If not specified shall be validated against LBS NCS configuration for the application
horizontalAccuracy QoS parameter defines the required horizontal accuracy for the location update.Accepted values and their precedence is as follows;

  1. 100
  2. 500
  3. 1000
  4. 1500

 

Minimum value 100 has the highest precedence.

 

Eg; Third party application can not initiate location requests with ‘100’ or ‘500’ if the provisioned value is ‘1000’. But can initiate location requests with ‘1000’ and ‘1500’.

 

ENUM Optional
If not specified shall be validated against LBS NCS configuration for the application
freshness QoS parameter defines the required freshness for the location update.Accepted values and their precedence is as follows;

  1. HIGH_LOW
  2. LOW_HIGH
  3. HIGH
  4. LOW

 

HIGH_LOW has the highest precedence.

 

Eg; Third party application can not initiate location requests with ‘HIGH_LOW’ if the provisioned value is ‘LOW_HIGH’. But can initiate location requests with ‘LOW_HIGH’, ‘HIGH’ and ‘LOW’.

 

ENUM Optional
If not specified shall be validated against LBS NCS configuration for the application

 

Response

Following is a sample LBS response with Mandatory and Optional parameters.


{
  "statusCode": "S1000",
  "timeStamp": "20130405181744",
  "subscriberState": true,
  "statusDetail": "Success",
  "horizontalAccuracy": "7.0",
  "longitude": "6.707778",
  "freshness": "8.0",
  "latitude": "79.948944",
  "messageId": "101304051246360081",
  "version": "1.0"
}

Following parameters need to appear in the LBS response as Mandatory parameters.

  • stastusCode
  • statusDetail
  • messageId
  • version

 

Following is a sample LBS response with mandatory parameters.


{
  "statusCode": "E1303",
  "statusDetail": "IP address, which the request originates from, is not listed within the allowed-host-address list",
  "messageId": "101304051248020083",
  "version": "1.0"
}

 

Following are the LBS Response parameters.

 

Parameter Name Description Type Mandatory / Optional
version API version shall be numbered as 1.0, 2.0 etc String Mandatory
messageID MessageID to uniquely Identify the request within the SDP String Will be specified always
latitude Latitude coordinate of the location of the subscriber String Mandatory if success.
Parameter will not be available for failed requests.
longitude Longitude coordinate of the location of the subscriber String Mandatory if success.
Parameter will not be available for failed requests.
freshness Actual freshness of the responded location update. Value shall be defined in minutes. Integer Mandatory
horizontalAccuracy Actual horizontal accuracy of the responded location update. Value shall be defined in meters. Integer Mandatory
subscriberState Power on/off state of the target subscriber’s mobile phone.
True: power on
False: power off
Boolean Optional
timeStamp System date and time of success or failed transaction Date time Mandatory if success.
Parameter will not be available for failed requests.
statusCode The error code for the request String Mandatory
statusDetail The error detail for the request String Mandatory