|Previous Article||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.
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
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.
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.
Used to specify the string which will separate the output address lines within the output Address field (default “<BR>”).
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.
Certified option which allows testing of a SERP compliant output for Canada (SERP Recognition still pending).
Used to specify the threshold at which to stop returning parse interpretations, as a percentage of the confidence of the top result. Default 90.
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.
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.
Used to specify the comma delimited list of fields to be searched for country information.
Used to specify the comma delimited list of custom fields to be searched for during the parse process.
Used to specify the confidence to be applied to the recognition of any fields recognized through the CustomFields option.
Used to specify the directory in which to find the Global Knowledge Repository.
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.
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.
Used to specify the ISO 3166-1 alpha-3 code which should be used for all input records.
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.
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.
Used to specify a filename for debug output.
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.
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.
Used to specify the maximum number of results to return in the ProcessResults structure.
Used to specify the minimum matchscore a record must reach in order to avoid reversion. Default is 0 (zero), valid values are 0-100.
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.
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.
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.
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’).
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
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.
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’.
Used to specify the number of MRU reference datasets to cache. Default value is 5.
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.
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.
Used to specify the list of fields that should be suppressed from the Address field output.
Used to specify the list of fields that should be suppressed from the output.
Used to specify the fields that should not be transliterated. Default “ID,ISO3166-2,ISO3166-3,_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC”.
Specify true to output extra debug information viewable using the getFieldInfo method.
Specify true to force the API to search for custom lexicons (lx__c.lfs files)
Specify false to limit transliteration to complete field phrase matches. Default true.
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.
Record the process input data to the specified debug log file.
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
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) -
This object contains the results of a call to the Process method. The properties are as follows -
This represents the Address Verification Code (AVC) of a call to the Process method.
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.
This property describes the status of the call to the Process method. Possible values are -
In the case of psException, the specific reason for the failure will be contained in the LastError property.
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.
This object represents all the information pertaining to a field of a match found in the Process method. The properties are as follows –
This property holds the name of the field as a string
This property holds the value of the field.
This property holds a measure of how confident the match of this particular field is in the matched record.
This property can contain further information on the matched field.
This property contains the score achieved for the field in the matched record.
This is a description of the what actions were taken on this field during the process. Potential values are
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 –
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 –
|Previous Article||matchIT Web Index|