Address Verification and Geocoding Plug-in

The Convergence Address Geocoding and Validation Plug-in uses the optional Convergence for Address Verification and Geocoding to provide an enricher for international postal addresses. This enricher cleanses, standardizes and enriches the postal addresses with geocoding and timezone information.

Convergence Address Enricher

Plug-in ID

Convergence Address Enricher - com.semarchy.engine.plugins.convergence.address

Description

This enricher takes an input address, enriches and validates this postal address using Convergence for Address Verification and Geocoding.

Plug-in Parameters

The following table lists the plug-in parameters.

Parameter Name Mandatory Type Description
On-Premise Host No String Host name or IP address of the Pool Manager server for an on-premise installation.
On-Premise Port No String Port of the Pool Manager service for an on-premise installation. The default value is 27920.
On-Demand URL No String URL of the on-demand service. To use this service, the ON_DEMAND pool must be specified in the Pool Names List in the plug-in parameter or plug-in input.
Data Elements Format No String Format used for the data elements returned by the enricher. Possible values are UPPERCASE, TITLECASE, LOWERCASE, NONE (default).
Pool Names List No String Comma-separated list of pool names to query. Use the ON_DEMAND pool name to explicitly use the on-demand service. The Pool Names List specified as a plug-in input overrides this value for specific records.

Pools and On-Demand/On-Premise Configuration

A pool represents a set of databases to search addresses in an on-premise setup of Convergence for Address Verification and Geocoding. Pools (identified by their Pool Name) are defined and managed by the Pool Manager server. The plug-in connects to this server using the On-Premise Host and On-Premise Port parameters and queries the pools specified in the Pool Names List.

Note: For more information about pools configuration and the pool manager, see the Capscan Pool Manager Documentation provided with your installation of Semarchy Convergence for Address Verification and Geocoding.

When performing an address query, the plug-in uses the Pool Names List (either provided as an input or parameter). The query is launched on each pool in the list until a pool is able to process the address.

In the Pool Names List, a specific pool called ON_DEMAND allows switching to on-demand processing. When this pool name appears in the list, the On-Demand URL is used to query the on-demand service. If ON_DEMAND only appears in the pool names list, the On-Premise Host and On-Premise Port parameters are unused.

Plug-in Inputs

The following table lists the plug-in inputs.

Parameter Name Mandatory Type Description
Address Line Yes String Address line to process. If the address is composed of multiple lines, then these lines must be provided as a comma-separated list of address lines.
Postal Code No String Postal code of the address. This value may be merged in the Address Line parameter.
City No String City of the address. This value may be merged in the Address Line parameter.
Country No String Country of the address. This value may be merged in the Address Line parameter.
Pool Names List No String Comma-separated list of pool names to query. Use the ON_DEMAND pool name to explicitly use the on-demand service. This list overrides the Pool Names List plug-in parameter for this record only.

Plug-in Outputs

The following table lists the plug-in outputs.

Parameter Name Type Description
Formatted Address: These outputs contain address information formatted and suitable for mailing purposes.
Address String Comma-separated list of address lines. This output contains the full formatted address.
Address Key String UK Address Key as defined by the Royal Mail.
Ambiguity: These outputs contain information for ambiguous matches.
Ambiguity List String Comma-separated list of address elements and postal codes of the form: “Address Elements;Postal Code”. This list is provided if the search result is ambiguous.
Ambiguity List Count Integer Count of entries in the ambiguity list.
Address Items: These outputs contain address tokens.
Organization String Organization Name.
Building Name String Name of the building.
Building Number String Number of the building.
Sub-Building String Sub-building information. Postal boxes (PO Box) information appear in this field.
Street String Street of the address.
Dependent Street String Street to which this address' street depends to.
Locality String Locality of the address.
Dependent Locality String Locality to which this address' locality depends to.
County String Name of the county or province.
Postal Code String Postal code.
Postal Town String Town or City.
Country String Country of the address.
Country Code String Country code.
Error Management: These outputs contain result and error codes for the processing of the address.
Result Code Integer Result code for the address search. See below for more information.
Error Code String Error code returned by the server.
Error Text String Error message returned by the server.
Address Quality: These outputs contain information about the quality of the output address and match process.
Field Status String 8 character string. Each character represents how each address element was matched. See below for more information.
Match Score Integer Percentage score describing the quality of the address match.
Match Level Integer Address element to which the address is matched. See below for more information.
Output Status String This output field contains the status of the address match; Whether Verified, Corrected, Parsed or Not Matched. See below for more information.
Postal Code Change Level String The level at which the matched postal code differs from the input postal code. See below for more information.
Input Postal Code Level Integer Level of postal code input: 0 - No post code, 4 – Postal code.
Output Postal Code Level Integer Level of postal code match: 0 - No post code, 4 – Postal code.
Geocoding: These outputs contain information about address geocoding.
Latitude Float GPS (WGS84) latitude in degrees decimal
Longitude Float GPS (WGS84) longitude in degrees decimal
Geocoding Level Integer Geocoding level for this address. See below for more information.
Geocoding Status String Geocoding status for this address. See below for more information.

Address Quality Outputs

The Match Score is the first output to consider to assess the quality of the address returned by the plug-in. In addition to this value:

The following values are returned in the Match Level output:

Value Description
0 No Match.
1 Town, City, Locality.
2 Street.
3 Premise.
4 Organization.

The following values are returned in the Output Status output:

Value Description
V Verified. The input address is verified as mailable without change.
C Corrected. The input address has been corrected in matching to the reference data.
P Parsed. The input address has been parsed but there is no matching reference data.
N Not matched. The input address cannot be matched or parsed.

The Field Status output contains 8 characters. Each character is a value that represents how each address element was matched.

Character positions in the Field Status output:

Position Address Element
0 Organization
1 PO Box
2 Building name, Building number
3 Street
4 Locality
5 City
6 Administrative area
7 Postal code

Character values in the Field Status output:

Value Description
0 Element Correct (no change)
1 Element Corrected (minor change)
2 Element Corrected (major change)
3 Element Not checked (no data)
4 Element Not found
5 Element Not provided

The following values are returned in the Postal Code Change Level output. This value reflects changes done on the postal code:

Value Description
K No postal code/ZIP code.
L Input postal code, no output postal code.
M Output postal code, no input postal code.
N No change.
P Postal code change.

Geocoding Outputs

Geocoding information is returned in the Latitude and Longitude outputs.
The quality of the geocoding information is exposed in the Geocoding Level and Geocoding Status outputs.

The following values are returned in the Geocoding Level output:

Value Description
5 Delivery Point (PostBox or SubBuilding).
4 Premise (Premise or Building).
3 Thoroughfare.
2 Locality.
1 Administrative Area.
0 None.

The following values are returned in the Geocoding Status output:

Value Description
P Point: A single geocode was found matching the input address
I Interpolated: A geocode was able to be interpolated from the input addresses location in a range
A Average: Multiple candidate geocode were found to match the input address, and an average of these was returned
U Unable to geocode: A geocode was not able to be generated for the input address

Error Management Outputs

The following values are returned in the Result Code field.

Value Description
0 An internal error occurred, see the Error Code and Error Text output for details.
1 The address was successfully matched or parsed.
2 No hits were found for this address.
3 Insufficient input details were provided for processing.
4 Ambiguous results. Refer to the Ambiguity list field for details.