Gazetteer - Address Finder

Overview

The Gazetteer Service, also known as the Address Finder service supports the validation or retrieval of UK-based addresses. The service will fulfil requests coming from systems external to Spine as well as those from internal clients. It is an address validation service accessing a separate address list Postal Address File (PAF)
The service requires a relatively low level of reliability and as such will implement an MHS relationship with the client in web service mode. The service will be provided via a SOAP web service defined by a WSDL. The Gazetteer provides the following functionality to external systems:

• Validate and transform the address to PAF standard
• Search and return address list based on search criteria

Gazetteer Functions

The Gazetteer service provides various functions for validating an address based on complete/partial address lines provided by the caller subsystems. This includes:

1. Single search result based on the house number/name and postcode.
2. Multiple search results on partial address inputs or wild card searches.
3. Fuzzy searches based on phonetics of words entered in address lines.
4. Intelligent postcode parsing to validate the underlying structure.
5. Return of the PAF address key for each delivery point.

Full details can be found in EIS 12.3 issue 11.9

GetAddressList

The validation or retrieval of addresses is performed using MHS Web Service Mode in response to the request sent by the external systems with a pre-defined set of search arguments. The response is returned as exact or multiple matches depending upon the completeness of search arguments. The matched addresses are returned to the client subsystem as retrieved from the PAF. The Gazetteer Service will return the lower of the total number of matched addresses found and the number of addresses requested by the client (up to the maximum number permitted by the service). The format of each returned address line in terms of size and capitalisation feature will be configured with the Gazetteer service. The PAF address key will also be returned along with each matched address. The address validation process will be carried out only for the UK addresses submission of a non-UK address will result with an error message containing ‘Unable to process non UK Address’ being sent back to the client.

The Gazetteer service will return all matched address as retrieved from the PAF file up to the service’s configured default figure where the client fails to provide a value for ‘maximum number of address to be returned’. The following table describes the possible search patterns and the corresponding response type.

Search Argument

The source systems will send up to maximum of six search arguments while calling the ‘Get Valid Address’. The search arguments normally map to typical postal address and will be as follows:

Search Capability

Search Mode

The search mode decides the search method to be followed by Gazetteer service taking the minimum number of search arguments. The following search mode will be supported by the Gazetteer service depending upon the availability of minimum address lines.

• OPTIMAL: The premises number or name and postcode must be present as part of the search criteria.
• ALTERNATIVE: If the Optimal mode is not possible i.e. the caller subsystem is unable to provide the premises number or name and postcode.

Returned Response

Upon a successful search based on the argument list provided by the calling system, one or more addresses may be returned. The Get Valid Address will return multiple addresses in the desired message format as described in the following. The response from Gazetteer service will include any error message for the requesting system to report where a failure of the search process occurs, including system failures. Each returned address will have the following format in the order shown in reference numbers 1-8 below; followed by a single integer element containing the total number of addresses matched (as this may be different to the number returned).

Interface Technical Description

GetAddressList: The message exchange protocol is a straight forward request-response interaction as shown in the following sequence diagram.

Figure 4 1. Get Address List Realisation.

Web Service Header

Gazetteer currently implements and will continue to support P1R1 version of the Web Service mode. As defined below under Web Services mode The Gazetteer header elements are included within the payload document in the SOAP body. Gazetteer does not use any aspects of the nasp:securityPackage. However, this element MUST be included as an empty element.

Error Handling Structure

Gazetteer returns application errors contained within the payload document in the SOAP body.

A Code Context element is included in the element schema classifying errors elements by service. This allows errors to use application specific or service specific error codes while avoiding duplication. The errorList/error/codeContext attribute for all Gazetteer errors MUST be “urn:nhs:names:errors:gazetteer”.

The following table describes the possible errors returned from Gazetteer. Successful responses will contain only the resulting data set and no error element.

Functional/Business Schema

The Gazetteer payload document structure is made up of the following elements (all from the national.carerecords.nhs.uk/Schema/ namespace):

• Request (getAddressListRequest):
  • The messageHeader element.
  • The postalAddress element. Contains the search parameters.
  • The maxNo element from the same namespace.
• Response
  • The messageHeader element.
  • The addressList element. Contains a collection of postalAddress elements containing the returned matches.
  • The totalmatches element.

Message Sample: SOAP / HTTP

The following shows an example of a Gazetteer getAddressListRequest.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header/>
	<SOAP-ENV:Body>
		<nasp:getAddressListRequest xmlns:nasp ="http://national.carerecords.nhs.uk/schema/">
			<nasp:messageHeader>
				<nasp:messageId>6e6bf479f2775defa378beea704051a4</nasp:messageId>
				<nasp:securityPackage/>
			</nasp:messageHeader>
			<nasp:postalAddress>
				<nasp:address1>1 Sandringham Crescent</nasp:address1>
				<nasp:address2/>
				<nasp:address3/>
				<nasp:town>Leeds</nasp:town>
				<nasp:county/>
				<nasp:postcode>LS178DB</nasp:postcode>
				<nasp:country/>
			</nasp:postalAddress>
			<nasp:maxno>2</nasp:maxno>
		</nasp:getAddressListRequest>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The response may look as follows:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header/>
	<SOAP-ENV:Body>
		<nasp:getAddressListResponse xmlns:nasp="http://national.carerecords.nhs.uk/schema/">
			<nasp:messageHeader>
				<nasp:messageId>1f52460:fb647de31b:-7ce2</nasp:messageId>
				<nasp:securityPackage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true" xsi:schemaLocation="http://national.carerecords.nhs.uk/schema http://gazetteer.co.uk/GSWS/gazetteer001.xsd"/>
			</nasp:messageHeader>
			<nasp:addressList>
				<nasp:postalAddress>
					<nasp:address1>1 Sandringham Crescent</nasp:address1>
					<nasp:address2/>
					<nasp:address3/>
					<nasp:town>LEEDS</nasp:town>
					<nasp:county>West Yorkshire</nasp:county>
					<nasp:postCode>LS178DB</nasp:postCode>
					<nasp:country>UNITED KINGDOM</nasp:country>
					<nasp:addressKey>17671560</nasp:addressKey>
				</nasp:postalAddress>
			</nasp:addressList>
			<nasp:totalmatches>1</nasp:totalmatches>
		</nasp:getAddressListResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Web Service Header

The P1R1 approach for Non-HL7 Web Service Header used NHS CFH (now known as NHS Digital) specific elements present in the headers. The Web Service Headers are derived from the WS-Addressing specification. A full definition of Web Service mode interactions can be found in part 2 MHS section 2.6 of the EIS documentation set.

Security Package

The SecurityPackage is depreciated but retained for future use.

Non-HL7 Web Service Header

The message header is used in web service mode when exchanging non-HL7 messages. It is only used for P1R1 web services, and will be depreciated in later releases.

Non-HL7 Web Services Error List

The errorList element is used in web service mode when exchanging non-HL7 messages. P1R1 web services use this element as part of a custom header.

Example Error Message

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/>
<SOAP-ENV:Body>
<nasp:getAddressListResponse xmlns:nasp="http://national.carerecords.nhs.uk/schema/">
    <nasp:messageHeader>
        <nasp:messageId></nasp:messageId>
        <nasp:errorList>
            <nasp:error>
                <nasp:codeContext>urn:nhs:names:errors:gazetteer</nasp:codeContext>
                <nasp:errorCode> GSS008</nasp:errorCode>
                <nasp:severity>Warning</nasp:severity>
                <nasp:description> Request time out occurred</nasp:description>
            </nasp:error>
        </nasp:errorList>
        <nasp:securityPackage/>
    </nasp:messageHeader>
</nasp:getAddressListResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>