W3.1 – International Address Verify Service Interface – Software Support

matchIT Web Index

The following section is a technical reference for the types and methods of the International Address Verify service, available as part of the findITS2AddressService application. Where self-explanatory, descriptions have been omitted.

InternationalAddressVerifyService

This is the main interface that offers the core address verification functionality. It contains one single method -

ProcessResult Process(Address address, ProcessOptions processOptions, Processes processes)

This method takes all the information provided in the input parameters, and performs the verification process accordingly. The return type on this method is a ProcessResult – for more information on this and the input parameters, see the object descriptions below.

Address

This object contains all the information relating to an address that requires verification. It is passed as the first argument to the Process method. Its properties are as follows –

string AddressStr – This is a comma delimited string of the whole address

string Address1

string Address2

string Address3

string Address4

string Address5

string Address6

string Address7

string Address8

string Address9

string Address10

string Address11

string Address12

string Country

string SuperAdministrativeArea

string AdministrativeArea

string SubAdministrativeArea

string Locality

string DependentLocality

string DoubleDependentLocality

string Thoroughfare

string DependentThoroughfare

string Building

string Premise

string SubBuilding

string PostalCode

string Organization

string PostBox

string Contact

string Function

string Department

string ThoroughfarePreDirection

string ThoroughfareLeadingType

string ThoroughfareName

string ThoroughfareTrailingType

string ThoroughfarePostDirection

string DependentThoroughfarePreDirection

string DependentThoroughfareLeadingType

string DependentThoroughfareName

string DependentThoroughfareTrailingType

string DependentThoroughfarePostDirection

string BuildingLeadingType

string BuildingName

string BuildingTrailingType

string PremiseType

string PremiseNumber

string SubBuildingType

string SubBuildingNumber

string SubBuildingName

string OrganizationName

string OrganizationType

string PostBoxType

string PostBoxNumber

Note that the applicability of the above properties will depend on the country that the address is associated with.

ProcessOptions

This object contains the properties that describe all the parameters you want to apply to the Process method – It is passed as the second argument to the method. The properties are listed below. Note that if any of the properties are not set, the default value will be used.

string FIS2AddressLineFormattingConfig

Used to specify the custom formatting configuration file for any of the returned address elements. If left blank, the standard formatting provided by the addressing engine is used. The name of this property is prefixed with FIS2 as it has been added and implemented at the wrapper level as part of findIT S2, and does not exist in the native addressing API.

string AddressLineSeparator

Used to specify the string which will separate the output address lines within the output Address field (default “<BR>”).

string CasingIgnoreFields

Used to specify the fields that should be ignored by the OutputCasing option. System default is “ID,PostalCode,PostalCodePrimary,PostalCodeSecondary,ISO3166-2,ISO3166-3,PostBox,PostBoxNumber,PostBoxType,_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC,AQI,HyphenClass,MatchedFieldList,DPS,CountryCode,Outputstatus,FormattedAddress”. Additionally, the following datasets also add AdministrativeArea to the default values: AUS, BRA, CAN, ITA, MEX, CHE, and USA. Currently system defaults cannot be overridden, but country-level values will be ignored when CasingIgnoreFields is used. Please re-use “AdministrativeArea” as a value to retain the default behaviour.

string CertifiedCountryList

Certified option which allows testing of a SERP compliant output for Canada (SERP Recognition still pending).

int ConfidenceThreshold

Used to specify the threshold at which to stop returning parse interpretations, as a percentage of the confidence of the top result. Default 90.

int ContextResultCacheSize

Used to specify how many sets of context results should be cached in memory. This cache is a cost-based cache based on processing time, meaning that the slowest context analyses have their results cached. Default 0. Values up to around 5,000 are relevant, but the memory usage and performance gain will be dependent on the supplied input data.

int ContextCountryCacheSize

Used to specify the number of MRU countries to generate ContextResult caches for. On an unsorted multi-country file a value of around 10 may be relevant, but the memory usage and performance gain will be dependent on the supplied input data.

string CountryFields

Used to specify the comma delimited list of fields to be searched for country information.

string CustomFields

Used to specify the comma delimited list of custom fields to be searched for during the parse process.

int CustomFieldConfidence

Used to specify the confidence to be applied to the recognition of any fields recognized through the CustomFields option.

string DataDirectory

Used to specify the directory in which to find the Global Knowledge Repository.

string DefaultCountry

Used to specify the ISO 3166-1 alpha-3 code which should be used if no identifiable country can be found in an input record.

int FieldNameWeight

Used to specify the default field name weight, between 1 and 255. Default 10. A larger value will give more precedence to the supplied field name, a smaller value will give more precedence to the GKR matches.

string ForceCountry

Used to specify the ISO 3166-1 alpha-3 code which should be used for all input records.

string GeocodeCountryList

Used to specify a comma-delimited list of ISO 3166-1 alpha-3 codes of acceptable countries to geocode. Input records from other countries will not return geocodes. The default is to process data from all countries.

bool IgnoreUnmatched

Allow unmatched input data within the address lines to be ignored during a Search process, meaning that a search can proceed matching only partial input data. Default false.

string LogFileName

Used to specify a filename for debug output.

int MatchScoreAbsoluteThreshold

Used to specify the minimum matchscore a record must reach in the Match process to be taken into account as a candidate for matching. Default value is 60 and the maximum value is 100.

int MatchScoreThresholdFactor

This is a value that is used as a factor of the highest matching result. The resulting value is then used as a cut-off for considering candidates for the results. The higher the value of the factor, the higher the chance of getting a good verification result. Default value is 95 and the maximum value is 100.

int MaxResults

Used to specify the maximum number of results to return in the ProcessResults structure.

int MinimumMatchscore

Used to specify the minimum matchscore a record must reach in order to avoid reversion. Default is 0 (zero), valid values are 0-100.

int MinimumPostcode

Used to specify the minimum postcode status a record must reach in order to avoid reversion. Default is 0 (zero), valid values are 0-8.

int MinimumVerificationLevel

Used to specify the minimum verification level a record must reach in order to avoid reversion. Default is 0 (zero), valid values are 0-5.

bool OutputAddressFormat

Used to specify whether to output an extra field for the Address block fields with the suffix ‘Format’ showing how the hierarchical field positioning has occurred. Default false.

CasingOptions OutputCasing

Used to specify the letter case to use for output fields. Enum values are ‘Upper’, ‘Title’, ‘Lower’ or ‘UseDefault’. Default ‘Title’ (which is also used when using the Enum val ‘UseDefault’).

string OutputScript

Related to transliteration - Used to specify the ISO 15924 Code in which the output should be encoded, if possible. Alternatively ‘Native’ should be specified to choose the correct country specific script value. At the time of writing, valid values are -

Latn – Latin (English transliteration wherever possible)

Cyrl – Cyrillic (Russia)

Grek – Greek (Greece)

Hebr – Hebrew (Israel)

Hani – Kanji (Japan)

Hans – Simplified Chinese (China)

Arab – Arabic (United Arab Emirates)

Thai – Thai (Thailand)

Hang – Hangul (South Korea)

Native – Output in the native script wherever possible

int QueryResultCacheSize

Used to specify how many sets of query results should be cached in memory. This cache is a cost-based cache based on query time, meaning that the slowest queries have their results cached. Default 0. Values up to around 5,000 are relevant, but the memory usage and performance gain will be dependent on the supplied input data.

RangeDecoposeOptions RangeDecompose

Used to specify how to expand ranges such as premise numbers and sub building numbers. Valid values are ‘Match’ (returning only the value matching the input query), ‘Range’ (returning a human-readable range, e.g. ’1-9 Odd’), or ‘Full’ (expanding out the range into its constituent numbers, e.g. ’1′, ’2′, ’3′, ’4′, ’5′). It is also possible to specify ‘UseDefault’.

int ReferenceDatasetCacheSize

Used to specify the number of MRU reference datasets to cache. Default value is 5.

int ReferencePageCacheSize

Used to specify the number of MRU pages to cache from each individual reference dataset. Default value is 12, each page equates to approximately 5Mb of memory use.

string SuppressAdditionFields

Used to specify the list of fields that should not be added to an output result if they do not appear in the input record.

string SuppressAddressFields

Used to specify the list of fields that should be suppressed from the Address field output.

string SuppressFields

Used to specify the list of fields that should be suppressed from the output.

string TransliterationIgnoreFields

Used to specify the fields that should not be transliterated. Default “ID,ISO3166-2,ISO3166-3,_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC”.

bool ToolInfo

Specify true to output extra debug information viewable using the getFieldInfo method.

bool UseCustomLexicons

Specify true to force the API to search for custom lexicons (lx__c.lfs files)

bool UseSymbolicTransliteration

Specify false to limit transliteration to complete field phrase matches. Default true.

string VerifyCountryList

Used to specify a comma-delimited list of ISO 3166-1 alpha-3 codes of acceptable countries to process. Input records from other countries will return the unprocessed Address Verification Code ‘U00-U00-P0-000′. The default is to process data from all countries.

string LogInput

Record the process input data to the specified debug log file.

string LogOutput

Record the process output data to the specified debug log file.

Processes

This is an enumeration of processes that are available from the Process method. The enumeration is a bit field, so in order to combine processes in one call, simply OR the values together as the third argument to the process method. Note that not all processes can run at the same time. Values are as follows –

Country = 1

Attempts to identify a country from supplied input data.

Parse = 2

Attempts to produce componentised output from fully or partially unstructured address data.

Match = 4

Finds the most closely matching record or records from the relevant reference data source to the supplied componentized input data.

Verify = 16

The Verify process is designed for batch environments, where the desire is to enter address information in address lines, address components or a combination of both and return the cleansed address data. Internally, the Verify process is implemented by running the Country, Parse, Match, and Format processes.

Geocode = 64

The Geocode process adds latitude, longitude, and GeoAccuracy where possible; typically used with either Verify or Search.

CASS = 512

For outputting CASS verified US addresses.

SERP = 1024

For outputting SERP verified Canadian addresses.

AutoComplete = 2048

For interactive environments where full or partial address data is provided as input and a set of possible matching results is returned as output.

Note that, whilst using strongly typed code it is easy to OR these values (such as using the pipe delimiter in .NET), when manually writing a text based SOAP request, the values are ORed simply by leaving a space between them. For example, using Verify with Geocode in SOAP would be achieved with the following (note the exact format of the nodes below may vary) -

<web:processes>Verify Geocode</web:processes>

ProcessResult

This object contains the results of a call to the Process method. The properties are as follows -

string AccuracyCode

This represents the Address Verification Code (AVC) of a call to the Process method.

List<ProcessResultItem> ResultItems

This property contains a list of results / matches that were found in the call to the process method. Depending on the Processes submitted as the third argument, and the address data, this list can contain any number of results. For instance, the ‘Verify’ process will only ever return one single result, whereas the ‘Search’ process can return multiple matches if ambiguities were detected.

ResultStatus Status

This property describes the status of the call to the Process method. Possible values are -

psException

psInvalidInputRecord

psOK

psServerUninitialized

In the case of psException, the specific reason for the failure will be contained in the LastError property.

string LastError

This property will contain information about any exceptions that occur in the case of a failure.

ProcessResultItem

This object contains all the information relating to a match found during a call to the Process method. The information for each field is contained in a ProcessResultItemField object, which is described further below, as is the type of the MachingInfo property, MatchInfo.

ProcessResultItemField AVC

ProcessResultItemField AddressStr

ProcessResultItemField Address1

ProcessResultItemField Address2

ProcessResultItemField Address3

ProcessResultItemField Address4

ProcessResultItemField Address5

ProcessResultItemField Address6

ProcessResultItemField Address7

ProcessResultItemField Address8

ProcessResultItemField Address9

ProcessResultItemField Address10

ProcessResultItemField Address11

ProcessResultItemField Address12

ProcessResultItemField DeliveryAddress

ProcessResultItemField DeliveryAddress1

ProcessResultItemField DeliveryAddress2

ProcessResultItemField DeliveryAddress3

ProcessResultItemField DeliveryAddress4

ProcessResultItemField DeliveryAddress5

ProcessResultItemField DeliveryAddress6

ProcessResultItemField DeliveryAddress7

ProcessResultItemField DeliveryAddress8

ProcessResultItemField DeliveryAddress9

ProcessResultItemField DeliveryAddress10

ProcessResultItemField DeliveryAddress11

ProcessResultItemField DeliveryAddress12

ProcessResultItemField Country

ProcessResultItemField CountryName

ProcessResultItemField ISO3166_2

ProcessResultItemField ISO3166_3

ProcessResultItemField ISO3166_N

ProcessResultItemField SuperAdministrativeArea

ProcessResultItemField AdministrativeArea

ProcessResultItemField SubAdministrativeArea

ProcessResultItemField Locality

ProcessResultItemField DependentLocality

ProcessResultItemField DoubleDependentLocality

ProcessResultItemField Thoroughfare

ProcessResultItemField DependentThoroughfare

ProcessResultItemField Building

ProcessResultItemField Premise

ProcessResultItemField SubBuilding

ProcessResultItemField PostalCode

ProcessResultItemField PostalCodePrimary

ProcessResultItemField PostalCodeSecondary

ProcessResultItemField Organization

ProcessResultItemField PostBox

ProcessResultItemField Unmatched

ProcessResultItemField Contact

ProcessResultItemField Function

ProcessResultItemField Department

ProcessResultItemField ThoroughfareType

ProcessResultItemField ThoroughfarePreDirection

ProcessResultItemField ThoroughfareLeadingType

ProcessResultItemField ThoroughfareName

ProcessResultItemField ThoroughfareTrailingType

ProcessResultItemField ThoroughfarePostDirection

ProcessResultItemField DependentThoroughfarePreDirection

ProcessResultItemField DependentThoroughfareLeadingType

ProcessResultItemField DependentThoroughfareName

ProcessResultItemField DependentThoroughfareTrailingType

ProcessResultItemField DependentThoroughfarePostDirection

ProcessResultItemField BuildingLeadingType

ProcessResultItemField BuildingName

ProcessResultItemField BuildingTrailingType

ProcessResultItemField PremiseType

ProcessResultItemField PremiseNumber

ProcessResultItemField SubBuildingType

ProcessResultItemField SubBuildingNumber

ProcessResultItemField SubBuildingName

ProcessResultItemField OrganizationName

ProcessResultItemField OrganizationType

ProcessResultItemField PostBoxType

ProcessResultItemField PostBoxNumber

ProcessResultItemField GeoAccuracy

ProcessResultItemField GeoDistance

ProcessResultItemField Latitude

ProcessResultItemField Longitude

MatchInfo MatchingInfo

FormatInfo FIS2FormattingInfo

ProcessResultItemField

This object represents all the information pertaining to a field of a match found in the Process method. The properties are as follows –

string Name

This property holds the name of the field as a string

string Value

This property holds the value of the field.

int Confidence

This property holds a measure of how confident the match of this particular field is in the matched record.

string Info

This property can contain further information on the matched field.

float MatchScore

This property contains the score achieved for the field in the matched record.

FieldStatus Status

This is a description of the what actions were taken on this field during the process. Potential values are

fsAdded

fsEmpty

fsIdentifiedAlias

fsIdentifiedContext

fsIdentifiedNoChange

fsNotApplicable

fsUnrecognized

fsVerifiedAliasChange

fsVerifiedLargeChange

fsVerifiedNoChange

fsVerifiedSmallChange

MatchInfo

This object represents the match information available for a particular match found during a call to the Process method. It gives an overall view of the various properties of a match, rather than the individual view shown for each field in the ResultItemField object. The properties are as follows –

int Confidence

int Start

int End

string Type

string Info

float MatchScore

FormatInfo

This object represents the format information available for a particular match found during a call to the Process method. It gives an indication of whether or not custom formatting was applied, and if so which formatting (file / country) was used. The properties are as follows –

bool CustomFormattingUsed

string FormattingConfigurationName

string FormattingCountryName

string FormattingInfoMessage

matchIT Web Index