Geocoding an address
Convert a postcode, place or street into a geographical location, as both latitude/longitude and northings/eastings.
Geocoding addresses can be used for plotting different points on a map or performing a range of different mapping calculations.
Our geocoding method can be used with a company's list of customer address details to plot on a UK map where their customers live. This can be valuable to inform a company’s marketing strategy, such as where to target advertising or devise regional promotions for example, and help develop more personalised and tailored products/services in general.
Mapping customer locations can also be useful to help companies’ logistics and delivery operations that need to get products to customers as quickly and cost-effectively as possible.
API method to use: geo_code
How it works
The method returns a latitude, longitude, northing and easting for a UK location when some, or all, of the following are supplied:
- Postcode
- Address
- Place
- Street
Please see the Documentation section for more information including a list of mandatory and optional parameters, and returned values.
Note: This method will only geo-code your inputted address details to the centre of the nearest postcode. To geo-code a specific address to the highest level of accuracy (an individual premises) please use our method address_geo_code.
Returns latitude, longitude, northing and easting of a UK postcode, address, place or street.
This is useful for plotting points on a map or performing a range of mapping calculations.
Knowing where in the country your customers are can help you deliver a better, more personalised service. Whether you use this information to effectively target your marketing campaigns or to analyse customer behaviour around the country, your goal can be easily achieved using our API.
This method will only geo-code your inputted address details to the centre of the nearest postcode. To geo-code a specific address to the highest level of accuracy (an individual premises) please use address_geo_code.
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. |
text | Enter a UK place name, address, street name or postcode. |
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_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_list | List of geo_data records. |
Error Codes
See the common error codes. There are no errors which are specific to this method.
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_res> <t2a_version_number>1.0.0.8</t2a_version_number> <status>ok</status> <geo_data_list> <geo_data> <north>450919</north> <east>462573</east> <country_code>GB</country_code> <latitude>53.950596</latitude> <longitude>-1.04804</longitude> <description>YO10 5NP</description> </geo_data> </geo_data_list> </geo_code_res>
There are two ways to authenticate your application with the T2A API. The two implementation examples on this page cover each type of authentication
We recommend using an API key for internal applications and the javascript key for public facing applications where you would want to protect your API key.
Please note: The examples below run on a sandbox environment which return sample data. To quality check the data we provide, up to 3 free searches are available in the demo tab with results showing live [REDACTED] data.
API key
<div class="geo-code-example"> <form class="geo-code-form"> <div class="form-group"> <label for="surname">Address</label> <input type="text" class="form-control" id="text" placeholder="Enter an address"> </div> <button type="submit" class="btn example-submit">Submit</button> </form> </div> <div class="results"> <div id="results-output"></div> <a class="results-return" href="#">Back to search</a> </div>
.geo-code-example, .results { margin: 20px auto; width: 400px; } form.geo-code-form, .results { background-color: #F6F6F6; border: 1px solid #CBCBCB; padding: 15px; } .example-submit { background-color: #F0614C; border-radius: 2px; font-size: 11px; font-weight: 400; color: #fff; text-transform: uppercase; letter-spacing: 0.193em; width: 138px; height: 41px; margin-top: 10px; } .results { display: none; } .results-return { font-weight: 600; color: #F0614C; } #results-output span { font-weight: bold; text-transform: capitalize; } #results-output hr { border-top: 1px solid #000; } .error { font-size: 11px; color: #f00; }
$(document).ready(function(){ $(".geo-code-form").submit(function(e) { e.preventDefault(); $('.error', $(this)).remove(); var text = $("#text"); if(!text.val()) { errorBefore("Please enter an address.", text); } if($('.error', $(this)).length) { $('.error', $(this)).first().next('input').focus(); } else { $.ajax({ url: 'https://api.t2a.io/rest/rest.aspx', dataType: 'json', data: { 'method' : "geo_code", 'api_key' : 'sandbox', 'text' : text.val(), 'output' : 'json' }, success: function(result){ if(result.status == "error") { $('#results-output').append('<p class="output"><strong>Error:</strong>' + result.error_code +'</p>'); } else { var i = 0; if(typeof result.geo_data_list !== "undefined") { result.geo_data_list.forEach(function(geo_data_list_item){ if(i>0){ $('#results-output').append('<hr>'); } var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details']; for (var key in geo_data_list_item) { if(!key.includes('id') && !exceptionsArray.includes(key) ) { var keyName = key.replace('_', ' '); $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + geo_data_list_item[key] + '</p>'); } } i++; }); } } $('.geo-code-example').hide(); $('.results').show(); } }); } }); $('.results-return').on('click', function(e){ e.preventDefault(); $('#results-output').empty(); $('.geo-code-example').show(); $('.results').hide(); }); }); function errorBefore(msg, insertBefore) { $('<p class="error">' + msg + '</p>').insertBefore(insertBefore); }
Javascript key
<div class="geo-code-example"> <form class="geo-code-form"> <div class="form-group"> <label for="surname">Address</label> <input type="text" class="form-control" id="text" placeholder="Enter an address"> </div> <button type="submit" class="btn example-submit">Submit</button> </form> </div> <div class="results"> <div id="results-output"></div> <a class="results-return" href="#">Back to search</a> </div>
.geo-code-example, .results { margin: 20px auto; width: 400px; } form.geo-code-form, .results { background-color: #F6F6F6; border: 1px solid #CBCBCB; padding: 15px; } .example-submit { background-color: #F0614C; border-radius: 2px; font-size: 11px; font-weight: 400; color: #fff; text-transform: uppercase; letter-spacing: 0.193em; width: 138px; height: 41px; margin-top: 10px; } .results { display: none; } .results-return { font-weight: 600; color: #F0614C; } #results-output span { font-weight: bold; text-transform: capitalize; } #results-output hr { border-top: 1px solid #000; } .error { font-size: 11px; color: #f00; }
$(document).ready(function(){ $(".geo-code-form").submit(function(e) { e.preventDefault(); $('.error', $(this)).remove(); var text = $("#text"); if(!text.val()) { errorBefore("Please enter an address.", text); } if($('.error', $(this)).length) { $('.error', $(this)).first().next('input').focus(); } else { $.ajax({ url: 'https://t2a.io/ajax/getExampleJSKey', dataType: 'json', success: function (result) { if (result.status) { $.ajax({ url: 'https://api.t2a.io/rest/rest.aspx', dataType: 'json', data: { 'method' : "geo_code", 'javascript_key' : result.javascript_key, 'domain' : "t2a.io", 'text' : text.val(), 'output' : 'json' }, success: function(result){ if(result.status == "error") { $('#results-output').append('<p class="output"><strong>Error:</strong>' + result.error_code +'</p>'); } else { var i = 0; if(typeof result.geo_data_list !== "undefined") { result.geo_data_list.forEach(function(geo_data_list_item){ if(i>0){ $('#results-output').append('<hr>'); } var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details']; for (var key in geo_data_list_item) { if(!key.includes('id') && !exceptionsArray.includes(key) ) { var keyName = key.replace('_', ' '); $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + geo_data_list_item[key] + '</p>'); } } i++; }); } } $('.geo-code-example').hide(); $('.results').show(); } }); } } }); } }); $('.results-return').on('click', function(e){ e.preventDefault(); $('#results-output').empty(); $('.geo-code-example').show(); $('.results').hide(); }); }); function errorBefore(msg, insertBefore) { $('<p class="error">' + msg + '</p>').insertBefore(insertBefore); }
This example first needs to call to a file on your server, which will provide the user with an API key from your javascript key.
In our example above we have used a PHP file located at ajax/getExampleJSKey
which looks like the example below
<?php $url = 'https://api.t2a.io/rest/rest.aspx' . "?method=javascript_key" . "&api_key=sandbox" . . "&domain=" . $_SERVER['HTTP_HOST']; . '&ip_address=' . get_user_ip() . "&lifetime_minutes=10"; $result = simplexml_load_file($url); if ($result->javascript_key) { echo (string)$result->javascript_key; }