Making a Location Request Using HTTP

Overview

The MX Telecom Location Gateway allows location requests to be made over HTTP. This page details the format of the HTTP requests which can be made to the MX Telecom Location Gateway.

Contents

• Making a location request using HTTP GET
• Parameters for requests
• Response from server
• Parsing plain text response from server
• Parsing XML response from server

Making a location request using HTTP GET

The MX Telecom Location Gateway exposes an HTTP interface allowing applications with internet connectivity to locate a mobile handset.

A request for a page using the structure shown below is all that is needed for you to locate a mobile handset using the MX Telecom Location Gateway. The response give by the Location Gateway can either be in plain text or XML format. The endpoints for these HTTP requests are:

	HTTP	HTTPS (SSL)
Plain text response	http://lbs.mxtelecom.com/PlainLocate	https://lbs.mxtelecom.com/PlainLocate
XML response	http://lbs.mxtelecom.com/Locate	https://lbs.mxtelecom.com/Locate

Requests should be sent as a HTTP GET or POST using the parameters listed below.

HTTP/1.1 is enabled so, if sending multiple packets, the TCP/IP connection should be kept open between requests.

Parameters for requests

Name	Required?	Description	Default
user	Yes	Username of the account to use
pass	Yes	Password
msisdn	Yes	MSISDN of the mobile phone (e.g. 447700900999). No leading "+" is required
timeout	No	Lifetime of request in seconds (maximum 120)	20
sync	No	false - Make request asynchronously true - Make request synchronously	true
note	No	Note that will be stored in the billing record (maximum 160 characters)
subaccount	No	Sub-account that will be stored in the billing record (maximum 10 characters)

The following example shows an HTTP requests understood by the MX Telecom Location Gateway returning an XML formatted response:

http://lbs.mxtelecom.com/Locate?user=yourusername&pass=yourpassword&msisdn=447700900999

If no timeout value is specified for an asynchronous request, the timeout duration will be set to a default value (currently 20 seconds).

If the request is made synchronously, the timeout duration will have a maximum value (currently 120 seconds), which may be reduced in future.

Response from server

With your response, you will receive a status code, indicating how your request has proceeded. If this status indicates an error, there will also be a plain text explanation, however, status codes are used for ease of parsing by applications.

Code	Meaning
0	Success
101	Internal Configuration Error
102	Internal Error processing your request
103	Could not contact WapMX Server
104	Request missing compulsory parameter e.g. no msisdn set
105	Error in the format of your parameters
106	Internal Error while storing your request
107	Too many simultaneous synchronous requests: try again later, or asynchronously
108	Authentication error (user/pass incorrect)
109	Your daily limit of requests for that user has been exceeded
110	Your monthly limit of requests has been hit
111	You are not allowed to locate that user
112	Access denied to that account from your ip
113	Internal error has occurred
201	Unknown error
205	Request expired
206	The operator has no location for that msisdn
207	The operator rejected the request for the location of that msisdn (e.g. msisdn not on that network, often caused by attempting to locate a Virgin Mobile handset with a T Mobile account)
209	Our connection to this operator is temporarily unavailable
210	Our connection to this operator is temporarily saturated - try again later
211	The user is roaming

Status codes 0 and 2xx (where x is a digit) indicate that you will be billed for the request.

Status codes 1xx indicate that you will not be billed.

For details of the response body, see Parsing plain text response from server and Parsing XML response from server below.

Parsing plain text response from server

If you submitted your request to the PlainLocate endpoint (eg. http://lbs.mxtelecom.com/PlainLocate) the server will reply in plain text. The format is most easily indicated by example:

1. Synchronous success

0       #status
7589    #requestid
111111  #msisdn
2003-05-15 10:30:14 +0100	#result date
52.658058   #latitude	
1.716111    #longitude
651413      #eastings
313188      #northings
TG514131    #landranger
750         #accuracy in metres (radius)

2. Failure

207    #status
7740   #requestid
111111 #msisdn
Request rejected by operator	#plaintext reason

3. Rejection

108                     #status
Authentication error	#plaintext reason

4. Asynchronous success

0       #status
7734    #requestid
111111  #msisdn

N.B. everything after and including the # is a comment.

• If the status is 0, the request has been successful.
• If the status is of the form 1xx (where x is a digit) the request has been rejected.
• If the status is of the form (2xx) the request has failed.

Again, if the request is accepted, the reply will have HTTP status 200; if the request is rejected, the reply will have HTTP status 403, with text indicating the error.

Parsing XML response from server

If you submitted your request to the Locate endpoint (eg. http://lbs.mxtelecom.com/Locate) the response body will contain an XML document, including either a requestid (if the request has been approved) or an error message explaining why it has been rejected.

If you make your request asynchronously, when the Location Gateway has completed the request, the result will be returned to your server over HTTP (see here for details). As a general guideline, if your request has been accepted, the server's reply will have HTTP status 200; if it has been rejected, the server's reply will have HTTP status 403.

The XML Schema of the response provided by the Location Gateway is available here. A DTD version is available here.

This gives rise to four different forms of response:

1. Synchronous success

This is the form of response when a synchronous request has been made (sync=true) and the user has been successfully located, or is the body of a POST request made when delivering the results of an asynchronous request using XML.

<?xml version="1.0"?>
<response requestid="680" status="0">
	<msisdn>111111</msisdn>
	<time>
		<localtime>2003-05-13 00:40:22</localtime>
		<offset>+0100</offset>
	</time>
	<location>
		<latitude>52.658058</latitude>
		<longitude>1.716111</longitude>
		<eastings>651413</eastings>
		<northings>313186</northings>
		<landranger>TG514131</landranger>
		<accuracy>927</accuracy>
	</location>
</response>

2. Failure

This is the form of response when a synchronous request has been made (sync=true) and the user has not been located, or is the body of a POST request made when delivering the results of an asynchronous request using XML.

<?xml version="1.0"?>
<response requestid="708" status="207">
	<msisdn>123456</msisdn>
	<time>
		<localtime>2003-05-13 00:40:22</localtime>
		<offset>+0100</offset></time>
	<error>
		<message>Request rejected by operator</message>
	</error>
</response>

3. Rejection

This is the form of response when a request has been rejected by the Location Gateway. This may happen due to an incorrect username/password, malformed request, insufficient credit, etc.

<?xml version="1.0"?>
<response status="108">
	<error>
		<message>Authentication error</message>
	</error>
</response>

4. Asynchronous success

This is the form of response when a request has been made with parameter sync=false. It simply provides an identifier for the transaction, which will be used again when the response is returned to the customer's server via HTTP request, and for any contact with MX Telecom support.

<?xml version="1.0"?>
<response requestid="675">
	<msisdn>111111</msisdn>
</response>

Internet Explorer users

Internet Explorer replaces error pages below a certain size with its own "friendly" HTTP error messages; this is likely to prevent you from viewing error messages returned by the Location Gateway.

To solve this, click on Tools > Internet Options, select the Advanced tab and uncheck Show Friendly HTTP error messages.

About MX Telecom MX Telecom is a leader in wireless technology. MX Telecom offers an easily accessible gateway to data, voice and video messaging services including 2-way and premium SMS, multimedia messaging, interactive voice response, location-based services, video short codes, Internet and TV related solutions. For more information, MX Telecom can be reached on 0845 666 7778, or via email at sales@mxtelecom.com.