Geo code a single address

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>