Method List

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.

API method to use: geo_code
|
Credits per use: 0.01

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'   : "",
                                '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;
        }

API Endpoint & Authentication

Demo

Enter an address to find its latitude/longitude and northings/eastings.

Price calculator

Price Calculator

Number of checks: 50 Price per check: 50p