Locate a landline number (Geo-Code Telephone Number)
Find out what you can do with our API...
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.
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.
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. |
| accuracy_radius | 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"?>
<geo_code_telephone_res>
<t2a_version_number>1.0.0</t2a_version_number>
<status>ok</status>
<mode>normal</mode>
<geo_data>
<north>451500</north>
<east>463500</east>
<latitude>53.9557039148469</latitude>
<longitude>-1.03379659189474</longitude>
<postcode>YO10 5HS</postcode>
</geo_data>
</geo_code_telephone_res>