Global Address Object:Interface Use

← Global Address Object Reference

Creating an Instance

1. Create an instance of the Global Address Object’s GlobalAddr Interface.

Set addPtr = new instance of GlobalAddr

The first set of steps is to initialize the instance of the GlobalAddr Interface.

2. 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.
3. Call the SetPathToGlobalAddrFiles function with file a path as a parameter pointing to the location of the Global Address Object reference data files.
4. 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.

CALL InitializeDataFiles RETURNING result

If result <> 0 THEN
	Call GetInitializeErrorString RETURN ErrorMessage
	Display ErrorMessage
Else
	Process Addresses
End If

5. At this point, we are ready to load the GlobalAddr with address input data for verification correction etc.

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.>