LBS API

LBS (Location Based Service)

Finding the location real time even on a feature phone is a possibility for your app on Ideamart! 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