Geo code a single address

Returns accurate geo-co-ordinates for a single address in England, Wales or Scotland.

Our service enables you to accurately pinpoint on a map the location of a single address within England, Wales or Scotland.

Key amongst the many uses for this method is the ability for delivery drivers to see a map on a mobile app of where a customer lives, making it easier for them to find the property. Similarly, companies’ operational and customer service staff can see exactly where a customer lives and where the goods/services need to be shipped to. Estate agencies and investigation organisations would also benefit from being able to accurately pinpoint on a map the location of a property.

API method to use: address_geo_code

Note: 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, however the geo_code method is available for these territories.

How it works

The method returns WGS84 Latitude and Longitude, plus OSGB36 Northing and Easting values and UPRN for a single address providing the following required information is entered:

  • Full UK Postcode
  • Address line 1

The method will attempt to identify a single address based on those parameters. If the entered parameters return a small number (2-6) of addresses 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.

Please see the Documentation section for more information including a list of mandatory and optional parameters, and returned values.

API method to use: address_geo_code
|
Credits per use: 4

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. A Unique Property Reference Number (UPRN) of the address location is also provided.

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.

Examples


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
YO104NY
YO10 4ny
addr1 6 norway drive
6
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:-

BT
IM
GY
JE

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



<address_geo_code_res>
	<mode>test</mode>
	<status>ok</status>
	<credit_used>0</credit_used>
	<t2a_version_number>3.2.8.5a</t2a_version_number>
	<geo_data>
		<north>45021</north>
		<east>49253</east>
		<latitude>54.345</latitude>
		<longitude>-1.452</longitude>
		<description>Imagination Walk, Heslington, York</description>
		<uprn>100012345678</uprn>
	</geo_data>
</address_geo_code_res>

API Endpoint & Authentication

Price calculator

Price Calculator

Number of checks: 50 Price per check: 50p