Geo-code a single address

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

API method to use: address_geo_code

Skip to demo


Convert a single address into a geographical location, as both latitude/longitude and northings/eastings.

This method returns accurate geo-co-ordinates for a single address in England, Wales or Scotland; there is no address-level data available for Northern Ireland, the Isle of Man or the Channel Islands – but the geo_code method is available for these territories.

The method requires a full UK postcode, and the first line of an address. The method will attempt to identify a single address based on those parameters. If the entered parameters return a small number (2-6) of address for which a user selection is required, the method is re-entered with an item from that list.

The method is ONLY chargeable when a single full geo-coded address is returned.

The data is returned as OSGB36 Northings and Eastings, plus WGS84 Latitude and Longitude values

Mandatory Parameters

None of the parameters are case sensitive apart from the api key or javascript key.

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.
postcode The full UK postcode of the address. The case is irrelevant, and the space is optional.
addr1 The first line of the address. In most cases, a house number is enough information, but supply the maximum possible information.
address_id Used ONLY where a previous invocation of method returned a short list of ambiguous addresses. When this parameter is used, it is the ONLY mandatory parameter.

Optional Parameters

Name Description
addr2 The second line of the address, if available.
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 <address_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 A geo_data record. This is only present when the method has returned the data for a single address
address_list List of address nodes partially filled.

This is returned if the method has identified between 2 and 6 ambiguous addresses that match the user input, but a final user selection is required.


Working Address

This example returns a single address. We present some variants of the parameters which are correct, and enough to return a single address

Parameter Value
postcode YO15 3AN
YO10 4ny
addr1 6 norway drive
6 nor

Returns Multiple Addresses for User Selection

This example returns a list of address nodes to allow the final user to select a single address.

Parameter Value
postcode YO15 3AN
addr1 LANGDALES Wharf

Multiple Addresses but One Position

This example would have returned multiple addresses. However, T2A has recognised that all addresses have the same latitude and longitude, so these are grouped.Please notw that only the first full address in that group is returned

Parameter Value
postcode YO10 4AF
addr1 Festival flats

Error Codes

Name Description
no_data_available The method has been invoked using a postcode for which there is no accurate address data. These are currently:-


See the common error codes. There are no other 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

		<description>Imagination Walk, Heslington, York</description>