CODE YOUR APPS

LBS – API

Overview

The LBS API which is based on MLP, allows Service Provider applications to send and receive location requests using a REST based API. Supported services are as follows.

  • Request Service – This service enables the Service Provider application to request location of a particular mobile number and TAP sends the location as a response.

HTTP Rest

In this context, both requests/responses used to exchange information are with content type “application/json”.

JSON Objects

JSON objects are used as content type to communicate between application and TAP. JSON is an open, text-based data exchange format; it is human-readable, platform independent, and supports a wide availability of implementations.

LBS

The LBS REST Service facilitates Service Providers to send requests and receive responses to and from TAP.

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

Get Location

Get Location service comprises of location request and location response

Location request URL for Get Location service is as follows:

http://(sdp.dns):7000/lbs/locate

Note: (sdp.dns) field should be the URL of the TAP live server.

Service Providers who tests third party applications via SDK shall use 127.0.0.1 as the (sdp.dns).

Request

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

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.

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 String Optional
If not specified shall be validated against the latest version
subscriberId MSISDN of the subscriber for which the location update is needed. Mandatory Only a single value 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 specified shall be 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 provisioned DELAY’. value But location if the is ‘LOW can initiate 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 specified shall be freshness for the location update

Accepted validated 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” provisioned value if the 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.

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

  • statusCode
  • statusDetail
  • messageId
  • version

Following is a sample LBS response with mandatory parameters.

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 API version shall be numbered as 1.0, 2.0 etc String Mandatory
version 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 API version shall be numbered as 1.0, 2.0 etc String Mandatory
version Power on/off state of the target subscriber’s mobile phone True: power on False: power off Boolean Optional

Status Codes and Error Codes

Status Codes (Non Retry able)

Code Description
S1000 Process completed successfully for all the available destination numbers.

Error Codes (Non Retry able)

Code Description
E1313 Authentication failed. No such active application with applicationId application-id, or no active service provider or the given password in the request is invalid.
E1303 IP address from which this request originated is not provisioned to send request to application application-id. Please use a provisioned system to send request or contact system admin to provision the new IP.
E1312 Request is Invalid. specify_the_reason Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request.
E1309 Requested LBS service is not allowed for this Application. Please check the issue with TAP system administrator.
E1315 Cannot find the requested service LBS or it is not active.
E1317 MSISDN in request is invalid or not allowed.
E1601 System experienced an unexpected error.
E1342 MSISDN is black listed. Not authorized to use the application application_name
E1343 MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
E1325 Format of the address is invalid. Expected format is “tel:94232323232”

Error Codes (Retry able)

Code Description
E1318 Transaction limit per second has exceeded. Please throttle requests not to exceed the transaction limit. Contact TAP admin to increase the traffic limit.
E1319 Transaction limit for today is exceeded. Please try again tomorrow or contact TAP admin to increase the transaction per day limit
E1603 Temporary System Error occurred while delivering your request.

LBS Specific Error Codes (Non Retry-able)

Code Description
E1367 Invalid QoS value parameter. (Invalid NBL request)
E1368 Invalid service type parameter. (Invalid NBL request)
E1369 Positioning method not supported. (Position cannot be found for the given combination of QoS parameters.)

What follows is a list of definitions of all terms, acronyms and abbreviations required to properly interpret this document.

  • API – Application Programming Interface
  • HTTP – Hyper Text Transfer Protocol
  • JSON – Java Script Object Notation
  • LBS – Location Based Service
  • MLP – Mobile Location Protocol
  • MO – Mobile Originated
  • MT – Mobile Terminated
  • MSISDN – Mobile Station Integrated Services Digital Network
  • NBL – North Bound Layer
  • NCS – Network Capability Service
  • QoA – Quality of Service
  • SLA – Service Level Agreement
  • SMS – Simple Message Service
  • USSD – Unstructured Supplementary Service Data