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.
For information on where to access this service - please refer here.
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.
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.
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 behavior.
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.
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
Parse = 2
Match = 4
Format = 8
Verify = 16
Search = 32
Geocode = 64
Query = 128
GKRInfo = 256
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>
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.
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
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
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
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