Global Address Object:Interface Use: Difference between revisions
Created page with "← Global Address Object Reference {| class="mw-collapsible" cellspacing="2" style="background-color:#f9f9f9; border:1px solid #aaaaaa..." |
No edit summary |
||
Line 178: | Line 178: | ||
==Functions for Processing Input== | ==Functions for Processing Input== | ||
There are 3 functions that process data provided to the Global Address Object, but only '''VerifyAddress''' utilizes the input parameters set in | There are 3 functions that process data provided to the Global Address Object, but only '''VerifyAddress''' utilizes the input parameters set in [[#Setting Paramters for Input|Setting Paramters for Input]]. '''TranslateText''' and '''TransliterateText''' are utilized to map or move any input value and language combination to another output value and language combination. | ||
===VerifyAddress=== | ===VerifyAddress=== | ||
Line 196: | Line 196: | ||
Transliteration is completely different from translation which involves a change in language which preserves the meaning. Translation, for example, recognizes the difference between son and sun as it moves between alphabets. | Transliteration is completely different from translation which involves a change in language which preserves the meaning. Translation, for example, recognizes the difference between son and sun as it moves between alphabets. | ||
Melissa Data's Global Address Object gives you the choice to use either translation or transliteration. | |||
===TranslateText=== | ===TranslateText=== | ||
Line 236: | Line 238: | ||
<Do we want to have a transliteration option of explicit to say it will force Moskva?> | <Do we want to have a transliteration option of explicit to say it will force Moskva?> | ||
</span> | </span> | ||
==Getting Results and Output== | ==Getting Results and Output== | ||
Line 241: | Line 244: | ||
===GetInputParameterNames=== | ===GetInputParameterNames=== | ||
'''GetInputParameterNames''' returns the application an array/list of input parameter names like the input values referenced in [[#Setting Parameters for Input|Setting Parameters for Input]]. '''GetOutputParameterNames''' functions in the same manner | '''GetInputParameterNames''' returns the application an array/list of input parameter names like the input values referenced in [[#Setting Parameters for Input|Setting Parameters for Input]]. | ||
===GetOutputParameterNames=== | |||
'''GetOutputParameterNames''' functions in the same manner as '''GetInputParameterNames''', but is specifically for getting outputted results from the address verification/correction process initialized with '''verifyAddress'''. | |||
For a complete list of input and output parameter names with definitions, see [[Global Address Object:Parameters|Parameters]]. | For a complete list of input and output parameter names with definitions, see [[Global Address Object:Parameters|Parameters]]. | ||
The GetOutputParameter function is the counterpart to | ===GetOutputParameter=== | ||
Sample Address | The '''GetOutputParameter''' function is the counterpart to '''SetOutputParameter'''. This function takes in a parameter name, such as administrativeArea and returns the value “Queensland” for an address such as the one below. | ||
91 Queen Street, Brisbane QLD 4000 Australia | |||
;Sample Address | |||
:91 Queen Street, Brisbane QLD 4000 Australia | |||
In this example, QLD is the administrative area (US terms State/Province) abbreviation for Queensland. | In this example, QLD is the administrative area (US terms State/Province) abbreviation for Queensland. | ||
<pre> | |||
House number = 91 | |||
Street = Queen Street | |||
Postal Code = 4000 | |||
Administrative Area = QLD | Administrative Area = QLD | ||
City/Locality = Brisbane | City/Locality = Brisbane | ||
Country Name = Australia | Country Name = Australia | ||
</pre> | |||
To pass this fielded address data to the object as parameters the following calls would be coded: | To pass this fielded address data to the object as parameters the following calls would be coded: | ||
<pre> | |||
Result = addPtr.SetInputParameter(“countryName”, “Australia”) | Result = addPtr.SetInputParameter(“countryName”, “Australia”) | ||
Result = addPtr.SetInputParameter(“premiseNumber”, “91”) | Result = addPtr.SetInputParameter(“premiseNumber”, “91”) | ||
Line 265: | Line 279: | ||
// Now that all input values are set, call verifyAddress to attempt to process input | // Now that all input values are set, call verifyAddress to attempt to process input | ||
Intval = VerifyAddress() | Intval = VerifyAddress() | ||
// Now get values if intval is successful | |||
If intval = true | |||
outputResult1 = addPtr.GetOutputParameter(“administrativeArea”) | |||
outputResult2 = addPtr.GetOutputParameter(“inputAdministrativeArea”) | |||
End if | |||
The variable outputResult1 contains the resulting administrative area, as already mentioned: Queensland. | </pre> | ||
Melissa Data has built into the Global Address Object a series of diagnostic level function calls which provide varying levels of detail about the performances of the object’s underlying components. | The variable outputResult1 contains the resulting administrative area, as already mentioned: Queensland. It important to note that outputResult2 also contains a value which is the original input value of QLD as administrative area. | ||
==Diagnostic Level Function Calls== | |||
Melissa Data has built into the Global Address Object a series of diagnostic level function calls which provide varying levels of detail about the performances of the object’s underlying components. These function calls are not currently published but can be made available to customers upon request. Please speak to your sales person about these functions if you want to know more. | |||
<span style="color:red"> | |||
<We may want to expand on this to describe the availability of other detail and underlying atom sets etc.> | <We may want to expand on this to describe the availability of other detail and underlying atom sets etc.> | ||
</span> | |||
[[Category:Global Address Object]] | [[Category:Global Address Object]] | ||
[[Category:Reference]] | [[Category:Reference]] |
Revision as of 23:01, 5 August 2014
← Global Address Object Reference
Creating an Instance
- Create an instance of the Global Address Object’s GlobalAddr Interface.
- If necessary, call SetLicenseString and pass the license string as mentioned in Licensing. Again, this is not necessary if the license string is provided as the recommended environment variable.
- Call the SetPathToGlobalAddrFiles function with file a path as a parameter pointing to the location of the Global Address Object reference data files.
- Call the InitializeDataFiles function. If it returns anything other than 0, then initialization has failed. Check the return value of the GetInitializeErrorString function to find out why this happened.
- At this point, we are ready to load the GlobalAddr with address input data for verification correction etc.
Set addPtr = new instance of GlobalAddr
The first set of steps is to initialize the instance of the GlobalAddr Interface.
CALL InitializeDataFiles RETURNING result If result <> 0 THEN Call GetInitializeErrorString RETURN ErrorMessage Display ErrorMessage Else Process Addresses End If
Setting Parameters for Input
Setting input address data is the first step in global address validation. Before any verification or correction can be completed, the originating input address data must be set into the Global Address Object’s input parameters. Parameters are set into the Global Address Object as name/value pairs. The complete list of name/value pairs for input and output can be found in Parameters.
So, using our Global Address Object addPtr defined previously, we will set the following sample address into the input parameters:
- Sample Address
- Carretera Rioseco 2
- 34170 Villamartín De Campos Palencia
- SPAIN
Result = addPtr.SetInputParameter(“countryName”, “Spain”) Result = addPtr.SetInputParameter(“inputAddressLine1”, “Carretera Rioseco 2”) Result = addPtr.SetInputParameter(“inputAddressLine2”, “34170 Villamartín De Campos Palencia”)
Notice that the input in this case is in an address line format. Global Address Object will attempt to field and parse these address lines before processing the verification and correction of the address data.
Here is a secondary input example with more discrete input of address elements.
- Sample Address
- Viale Avignone 9
- 53100 Siena Siena
- ITALY
Here is the fielded version of this address:
- Sample Address
- House number = 9
- Postal Code = 53100
- Street = Viale Avignone
- Administrative Area = Siena
- City/Locality = Siena
- Country Name = ITALY
To pass this fielded address data to the object as parameters the following calls would be coded:
Result = addPtr.SetInputParameter(“countryName”, “ITALY”) Result = addPtr.SetInputParameter(“premiseNumber”, “9”) Result = addPtr.SetInputParameter(“PostalCode”, “53100”) Result = addPtr.SetInputParameter(“AdministrativeArea”, “Siena”) Result = addPtr.SetInputParameter(“Locality”, “Siena”) Result = addPtr.SetInputParameter(“thoroughfareName”, “Viale Avignone”)
As this input is fielded there is no need for the Global Address Object to parse the input address elements and they will be utilized as fielded for verification and/or correction.
Lastly, when setting the input parameter(s) there is also the need to specify some configuration values related to what you want the Global Address Object to do with the input address during processing. For example if you would like the results in a different alphabet than originally submitted the output options need be to be specified as a value.
- Sample Address
- Москва Москва Мо Мещанский Улица Троицкая 9 Корп 1 Оф. 133 Подъезд 3 129090
- RUSSIAN FEDERATION
- House number = 9
- Street = Улица Троицкая
- Postal Code = 129090
- Administrative Area = Москва
- City/Locality = Москва
- Country Name = RUSSIAN FEDERATION
To pass this fielded address data to the object as parameters the following calls would be coded:
Result = addPtr.SetInputParameter(“requestedOutputType”, “Native”) Result = addPtr.SetInputParameter(“countryName”, “RUSSIAN FEDERATION”) Result = addPtr.SetInputParameter(“premiseNumber”, “9”) Result = addPtr.SetInputParameter(“PostalCode”, “129090”) Result = addPtr.SetInputParameter(“AdministrativeArea”, “Москва”) Result = addPtr.SetInputParameter(“Locality”, “Москва”) Result = addPtr.SetInputParameter(“thoroughfareName”, “Улица Троицкая”)
Setting the requestedOutputType parameter tells the Global Address Object to return the results based on the language/alphabet parameter specified. This is accomplished via either translation, transliteration, or a combination of both.
Once we have our parameters set, we are ready to make the processing call to do some work on the input address data.
Functions for Processing Input
There are 3 functions that process data provided to the Global Address Object, but only VerifyAddress utilizes the input parameters set in Setting Paramters for Input. TranslateText and TransliterateText are utilized to map or move any input value and language combination to another output value and language combination.
VerifyAddress
The VerifyAddress function takes in no parameters, but reads from the values set in the SetInputParameter call(s) to attempt to process the input data for fielding, parsing, verification/correction and return formatting. The results from calling VerifyAddress are accessible by utilizing the functions defined in Getting Results and Output.
The call is very straightforward, but again, dependent on input parameters being defined.
Intval = VerifyAddress()
The return integer intval from this call has no determination or value related to the results of the call. The return only defined a 0 or 1 for the success or failure of the function call itself. Getting to the results of the VerifyAddress call itself, is the job of GetOutputParameter and GetOutputParameterNames.
Moving Between Alphabets and Character Sets
Most address quality tools deploy only one type of technology for moving address data between alphabets and languages and this is typically referred to as Character Set Mapping Technology (CSMT) or transliteration. Transliteration is the practice of transcribing or mapping a word or text in one writing system into another writing system. This is done word by word and/or letter by letter. Most mappings for transliteration map to letters with similar pronunciation, thus they include elements of transcription which specifically maps the sounds of one letter to the best matching script in another language.
Transliteration is completely different from translation which involves a change in language which preserves the meaning. Translation, for example, recognizes the difference between son and sun as it moves between alphabets.
Melissa Data's Global Address Object gives you the choice to use either translation or transliteration.
TranslateText
The TranslateText function attempts to provide a very specific translation of the input data into the destination language/alphabet. This is accomplished through the extensive reference data Melissa Data uses for address quality and in most cases maintains the meaning in the destination alphabet.
Var outputResult as string Var inputval as string Inputval = “Москва” Result = addPtr.TranslateText(outputResult,inputval ,”Cryllic”, ”English”) If Result = true Print outputResult ‘ This should output the word: Moscow End if
In the previous code the expected result is the correct English translated spelling of Москва which is Moscow. Compare this with the results from TransliterateText.
TransliterateText
The TransliterateText function utilizes character set mapping of the input data to arrive at the appropriate output/destination language/alphabet. This is accomplished through the extensive reference data Melissa Data uses for address quality and in most cases maintains the meaning in the destination alphabet.
<INSERT EXAMPLE OF A CSMT table for an alphabet from Latin to another alphabet like Cyrillic>
The code here looks similar but the results can be different:
Var outputResult as string Var inputval as string Inputval = “Москва” Result = addPtr.Transliterate(outputResult,inputval ,”Cryllic”, ”Latin”) If Result = true Print outputResult ‘ This should output the word: Moskva End if
The function takes very similar inputs but the outputs are different, Москва explicitly transliterated to Latin is Moskva, not Moscow. Melissa Data utilizes the best of transliteration with transcription as well as translation in address validation and correction and will produce the best Latin match of Moscow.
<Do we want to have a transliteration option of explicit to say it will force Moskva?>
Getting Results and Output
There are three functions available for getting return values and results from the Global Address Object: GetInputParameterNames, GetOutputParameterNames and GetOutputParameter.
GetInputParameterNames
GetInputParameterNames returns the application an array/list of input parameter names like the input values referenced in Setting Parameters for Input.
GetOutputParameterNames
GetOutputParameterNames functions in the same manner as GetInputParameterNames, but is specifically for getting outputted results from the address verification/correction process initialized with verifyAddress.
For a complete list of input and output parameter names with definitions, see Parameters.
GetOutputParameter
The GetOutputParameter function is the counterpart to SetOutputParameter. This function takes in a parameter name, such as administrativeArea and returns the value “Queensland” for an address such as the one below.
- Sample Address
- 91 Queen Street, Brisbane QLD 4000 Australia
In this example, QLD is the administrative area (US terms State/Province) abbreviation for Queensland.
House number = 91 Street = Queen Street Postal Code = 4000 Administrative Area = QLD City/Locality = Brisbane Country Name = Australia
To pass this fielded address data to the object as parameters the following calls would be coded:
Result = addPtr.SetInputParameter(“countryName”, “Australia”) Result = addPtr.SetInputParameter(“premiseNumber”, “91”) Result = addPtr.SetInputParameter(“PostalCode”, “4000”) Result = addPtr.SetInputParameter(“AdministrativeArea”, “QLD”) Result = addPtr.SetInputParameter(“Locality”, “Brisbane”) Result = addPtr.SetInputParameter(“thoroughfareName”, “Queen Street”) // Now that all input values are set, call verifyAddress to attempt to process input Intval = VerifyAddress() // Now get values if intval is successful If intval = true outputResult1 = addPtr.GetOutputParameter(“administrativeArea”) outputResult2 = addPtr.GetOutputParameter(“inputAdministrativeArea”) End if
The variable outputResult1 contains the resulting administrative area, as already mentioned: Queensland. It important to note that outputResult2 also contains a value which is the original input value of QLD as administrative area.
Diagnostic Level Function Calls
Melissa Data has built into the Global Address Object a series of diagnostic level function calls which provide varying levels of detail about the performances of the object’s underlying components. These function calls are not currently published but can be made available to customers upon request. Please speak to your sales person about these functions if you want to know more.
<We may want to expand on this to describe the availability of other detail and underlying atom sets etc.>