Geo-Code a Telephone Number

Find out what you can do with our API...

API method to use: geo_code_telephone

Skip to demo

Mobile location unavailable

We are currently unable to offer a service to geo-code a mobile telephone number. You can however still use the service to geo-code a landline.


Returns approximate position of a UK telephone number. This service must be approved by the mobile operators; we will process the application on your behalf.

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking server-side. If invoking from the browser via JavaScript, generate a JavaScript key using the javascript_key method.
telephone_number Enter a UK telephone number. Please note that mobile location is only available after your service has been approved by the mobile operators.

Optional Parameters

Name Description
client You can optionally include an identifier for your final client or user. This is logged in your usage log and you will be able to view your usage statistics by client.
output Set to json for a JSON response; the default response is XML. Not applicable to the SOAP API.
callback When using JSON, specify a JSONP wrapper in which the JSON response is to be wrapped.

Returned Values

The XML response is contained within a <geo_code_telephone_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code Returns the error code when the status is error. See below for error codes.
t2a_version_number The current API version number.
credit_used The number of credits used in order to execute the request.
mode Returns normal or test when executed in the free test mode.
geo_data A geo_data record. Note that the postcode is a sample postcode in the vicinity of the telephone number's location.

Returned when a mobile number is in use.

T2A always returns the location of the handset as a circle centered on the co-ordinates, with a radius in metres specified by this value. Expect values of 300-500m in dense urban areas, degrading to 1000-5000m in rural areas.
name Place or point of interest near the number.
containing_name Town that the number is near or within.
containing_name2 County or district that the number is within.
date_time A date_time record showing the approximate date and time (GMT) that the location was computed.
postcode_area The first part of the postcode (e.g. DT4).

Error Codes

Name Description
method_not_authorised_for_mobile Your service has not yet been approved by our supplier (on behalf of the mobile phone companies). We are therefore unable to report the position of a mobile telephone.
customer_private The mobile phone has been set to not report its location to services such as ours.

See also the common error codes.

Free Test Mode

When operating in the free test mode errors are returned if mandatory parameters are missing, or it returns a dummy data response, in an identical format to a real response.

Note that the mode is returned as test when the method is operating in the free test mode.

Example XML Response

<?xml version="1.0"?>
    <postcode>YO10 5HS</postcode>