Receiving a Location Response 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 made by the MX Telecom Location Gateway to your server in response to an asynchronous location request.

Contents

• Receiving a location response using HTTP
• Response format
• Parsing plain text response
• Parsing XML response
• Response to your server
• Security considerations

Receiving a location response using HTTP

The MX Telecom Location Gateway will push asynchronous location response by making an HTTP GET to the provided URL.

Response format

When a location response is available for a location request which was made asynchronously (sync=false) we will make an HTTP request to your server.

• If your account has been configured for HTTP POST, please refer to the Parsing XML response section further down this page.
• If your account has been configured for HTTP GET, details of the request can be found in the Parsing plain text response section immediately below.

Parsing plain text response

If the request was successful the following parameters will be given:

Parameter	Description
requestid	ID of the request
msisdn	MSISDN of the phone you were trying to locate
localtime	The time at which the phone was at the specified location Format: yyyy-MM-dd HH:mm:ss
offset	The offset from GMT Format +HHHH
status	Status code of the request. See here for the possible values.
latitude	Format +/-DD.dddd
longitude	Fomat +/-DD.dddd
accuracy *	Accuracy of result in metres (where available)
eastings	Conversion of latitude value
northings	Conversion of longitude value
landranger	Landranger co-ordinates

Note that optional parameters are marked with a *

An example request might be:

http://www.server.com/servlet?requestid=1&msisdn=447700900999;&localtime=2003%2D01%2D01+00%3A00%3A00&offset=%2B0100&status=0&latitude=50%2E1234&longitude=0%2E0&accuracy=100&eastings=123456&northings=654321&landranger=TQ209785&accuracy=500

If the request failed (the handset could not be located) then the following parameters will be given:

Parameter	Description
requestid	ID of the request
localtime	The time at which the request failed Format: yyyy-MM-dd HH:mm:ss
offset	The offset from GMT Format +HHHH
status	Status code of the request. See here for the possible values.
error	An error message to indicate what went wrong

An example request might be:

http://www.server.com/servlet?requestid=1&msisdn=447700900999&localtime=2003%2D01%2D01+00%3A00%3A00&offset=%2B0100&status=205&error=Request+expired

Parsing XML response

The body of the HTTP POST will contain an XML document with the result of the location request.

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

1. Synchronous success

This is the form of response when the user has been successfully located.

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

2. Failure

This is the form of response when the user has not been located.

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

Response to your server

Your server should respond with an HTTP 200 response with a non-empty body. This response must be given in a timely manner (sub 10 seconds) currently we do not abandon a request (waiting for the HTTP response) until 60 seconds have passed but this might be reduced in future.

Security considerations

To ensure the authenticity of the HTTP requests you should only accept requests from the following MX Telecom IP addresses:

• 83.166.68.0/23 (ie 68.0 -> 69.255)

The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.

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.