RightAddress

online real-time data hygiene and enhancement tool

Index

1. What is RightAddress?

2. How can RightAddress be used to process my data?

3. What data can be returned by RightAddress?
   
   3.1     SOA Codes
   3.2     SOA Reason Codes
    

4. Sample setup for VB.NET2003

5. Sample setup for VB.NET 2005

6. Sample setup for Java web integration

   6.1.    Required Tools

   6.1.1.     Download JAVA Sample Source Code

   6.2.    Creating Web Services Artifacts

   6.3.    Using the Artifacts

   6.4.    Within an IDE

7. Sample setup for processing a database using MS Access

   7.2.11    Download Sample MS Access application
   
    

RightAddress is an online web service that enables any modern computer application to format and enhance any NZ or Australian address in real time.  RightAddress uses Acxiom’s NZ and Australian PAFlink software to provide address verification against both the NZ Post and Australia Post Postal Address Files, on a record per record basis.  Thereby enabling a single Australasian database to have correct address details for both Australian and NZ addresses.

RightAddress ensures the address data held in your computer systems is formatted correctly with correct PostCodes, DPID's, MeshBlocks, XY Coordinates, Stat Boundaries etc.

No need for the expensive and risky extraction of addresses from your system, sending them to a third party and then reloading them back into your database a week or so later.  Hoping that you get the right address with the right person and that nothing has changed in that week.

Marketing do not need to wait for updating before the extraction and segmentation of customer data.  The data is always as up to date as the addresses you have.

RightAddress can be integrated into any modern database or system by your internal systems support or package vendor support or development people.

Statement of Accuracy reporting is also provided - allowing you to report on your whole database or on any defined segment of your database.

RightAddress is an online web service that can process data in two ways:

2.1.    Online integrated into your existing computer systems so that when any address is entered or changes the new cleaned address and additional information is returned and can be used to update your database. 

RightAddress will analyse your address and return NZ or Australian details or an error code if the address is invalid, all in real time with no logic required on within your application.  For example a user may enter an address into a call centre application or account maintenance form and immediately* the standardised, corrected and enhanced address details are returned.  Depending upon your application these details can be either written directly into your database or displayed prior to the record being saved into the system.

2.2.    When integrated into your customer facing web forms a customer can enter their address and after clicking submit (or immediately with some web development technologies) the enhanced address can be displayed over or next to the entered address. 

Data Returned depending upon your RightAddress purchased Package.

The Postal Address File contains only address data. This means that additional information such as individual and company names will not assist in verifying addresses through RightAddress.  Any name information should be kept separate from address information to avoid confusion when the address is being parsed and matched.

RightAddress searches in address fields for abbreviations of address elements such as flat or unit type, floor type, street type, and street suffix. In some cases these are one or two character abbreviations.  It is possible for non-address data to contain these abbreviations and if not specified as non-address data, RightAddress will add the full element name to the output address, producing an incorrect match (albeit, correct by the rules). Take the following example input containing an account designation:

        G SMITH

        70 GRAMPIAN RD

        ST HELLIERS

        AUCKLAND 1005

This can produce the following corrected address output:  

        GROUND FLOOR SMITH

        70 GRAMPIAN ROAD

        ST HELLIERS

        AUCKLAND 1005 

which is obviously not what was intended.

3.1.    SOA Codes

The SOA, or StatementOfAccuracyCode field indicates the classification of a record for the purpose of the Statement of Accuracy.

3.2.    SOA Reason Codes

The SOR, or StatementOfAccuracyReason field indicates why a record has been classified as INVALID for a Statement of Accuracy.

3.3.    Correction Codes

The CHG, or CorrectionCode field provides an indication as to the changes that have been made to the input address elements during the matching process. The following table lists the change codes that may be output from RightAddress either individually or in combination, separated by a single space. The reported changes may sometimes appear to reflect a more severe change than has occurred. Correction codes prefixed with “NZ” have been made by the parser, the record may not ultimately be verified against the PAF.

3.4.    Error Codes

The ERR, or ErrorCode field indicates that either a fatal or non-fatal error has occurred. Error codes in the range 1000 - 1999 should be treated as fatal errors and any results must be discarded.  Error codes in the range 2000 - 2999 are non fatal allocation error codes, and indicate that a match, or exact match, wasn’t found for the input address. Allocation error codes give a general reason why a PAF match wasn’t found but as RightAddress tries to match through multiple correction strategies care is needed in interpretation. Records with error codes 0, 2018 and 2020 are all returned with a DPID and an address. Records with an error code of 2009 return a corrected/standardised address but no DPID. No DPID allocation or address correction is performed for records returned with any other allocation error code.  Error codes in the range 3000 - 3999 indicate an error has occurred during pre-processing of the request.

4.2.    Click on the File menu, click New and select Project

4.3.    Select Windows Application from the Templates, and enter the project name and location

4.4.    From the Solution Explorer right click on References and click Add Web Reference.  If the Solution Explorer is not open, open it by clicking on the View menu and selecting Solution Explorer.

4.5.    Type in the following URL for the RightAddress web service http://rightaddress.simplicitycrm.com/rightaddress.asmx

4.6.    Click Go and wait for Visual Studio to locate the RightAddress web service.  If Visual Studio is unable to locate the web service, check your internet connection and try again.

4.7.    Change the Web reference name to RightAddress and click Add Reference

4.8.    The RightAddress web reference is now available in your project

4.9.    Create a test form and add the required controls as below

4.10.    To create the RightAddress service object use the following code:

Dim rightAddress As RightAddress.RightAddressSvc
rightAddress = New RightAddress.RightAddressSvc

4.11.    Log in to RightAddress using the Login method, providing the client ID, user name and password.  If the login is successful a  token will be returned which is used for subsequent calls to RightAddress.  The following code is used to log in to RightAddress:

Dim token As String
token = rightAddress.Login(tbClientID.Text, tbUserName.Text, tbPassword.Text)

4.12.    The main method called when using RightAddress is FormatAddress.  The FormatAddress method performs all the work, and will return the information specified in Section 3 of this document based on which package has been purchased.  NB: FormatAddress will always return the same object type with an incomplete set of fields populated for packages which have not been purchased.  The following code is used to call the FormatAddress method:

Dim address As rightAddress.Address
address = rightAddress.FormatAddress(token, "", True, tbAddressLine1.Text, tbAddressLine2.Text, tbAddressLine3.Text, tbSuburb.Text, tbTown.Text, tbCountry.Text, "", tbPostCode.Text)

4.13.    When all processing is complete, a call to the Logout method is required.  Failure to call Logout may result in future calls to Login being blocked for a short period of time.  RightAddress limits the number of concurrent sessions for each client ID, so unless Logout is called RightAddress will wait until logged in sessions time out before permitting a new session to begin.  The following code is used to log out from RightAddress:

rightAddress.Logout(token)

4.14.    Click here to download the Visual Studio 2003 RightAddress sample.  The sample solution contains complete VB.NET source code.  The sample code is a sample only and requires enhancement for production use.

5.2.    Click on the File menu and select New Project

5.3.    Select Windows Application from the Templates, and enter the project name

5.4.    From the Solution Explorer right click on the project and select Add Web Reference.  If the Solution Explorer is not open, open it by clicking on the View menu and selecting Solution Explorer.

5.5.    Type in the following URL for the RightAddress web service http://rightaddress.simplicitycrm.com/rightaddress.asmx

5.6.    Click Go and wait for Visual Studio to locate the RightAddress web service.  If Visual Studio is unable to locate the web service, check your internet connection and try again.

5.7.    Change the Web reference name to RightAddress and click Add Reference

5.8.    The RightAddress web reference is now available in your project

5.9.    Create a test form and add the required controls as below

5.10.    To create the RightAddress service object use the following code:

Dim rightAddress As RightAddress.RightAddressSvc
rightAddress = New RightAddress.RightAddressSvc

5.11.    Log in to RightAddress using the Login method, providing the client ID, user name and password.  If the login is successful a  token will be returned which is used for subsequent calls to RightAddress.  The following code is used to log in to RightAddress:

Dim token As String
token = rightAddress.Login(tbClientID.Text, tbUserName.Text, tbPassword.Text)

5.12.    The main method called when using RightAddress is FormatAddress.  The FormatAddress method performs all the work, and will return the information specified in Section 3 of this document based on which package has been purchased.  NB: FormatAddress will always return the same object type with an incomplete set of fields populated for packages which have not been purchased.  The following code is used to call the FormatAddress method:

Dim address As rightAddress.Address
address = rightAddress.FormatAddress(token, "", True, tbAddressLine1.Text, tbAddressLine2.Text, tbAddressLine3.Text, tbSuburb.Text, tbTown.Text, tbCountry.Text, "", tbPostCode.Text)

5.13.    When all processing is complete, a call to the Logout method is required.  Failure to call Logout may result in future calls to Login being blocked for a short period of time.  RightAddress limits the number of concurrent sessions for each client ID, so unless Logout is called RightAddress will wait until logged in sessions time out before permitting a new session to begin.  The following code is used to log out from RightAddress:

rightAddress.Logout(token)

5.14.    Click here to download the Visual Studio 2005 RightAddress sample.  The sample solution contains complete VB.NET source code.  The sample code is a sample only and requires enhancement for production use.

6.1.    Required Tools

• Java 2 Platform Standard Edition. Minimum required version 1.4.2.
• Web service APIs. Included in J2SE6, the latest version of Java as of this date.

6.1.1    Download RightAddress JAVA Sample source code

6.2    Creating Web Service Artifacts

6.2.1. From the command line navigate to the location of the installed Java platforms command line tools. This is usually located at C:\Program Files\Java\jdk<versionnumber>\bin.

6.2.2. Run wsimport with the following arguments

wsimport -d <destdir> -s <srcdir> -p <packagename> <webserviceurl>

            -d <destdir>               -: The directory to place generated .class files.

            -s <srcdir>                  -: The directory to place generated .java files.

            -p <packagename>    -: Optional package to place the files in.

            <webserviceurl>        -: The url of the webservices service description.

 Example: webservice located at http://services.simplicitycrm.com/addressright/addressright.asmx

            wsimport

-d "C:\Documents and Settings\Matthew Revell\My Documents\Tests\Java web service\BuildFiles"

-s "C:\Documents and Settings\Matthew Revell\My Documents\Tests\Java web service\ SourceFiles"

-p addressrightsvc

http://services.simplicitycrm.com/addressright/addressright.asmx?WSDL

This creates a class for each operation in the webservice plus two classes bearing the same name of the webservice. These two classes, a Service Factory and an Interface, are used to call the webservices methods.

In the above example these classes will be AddressRightSvc and AddressRightSvcSoap.

6.3.    Using the Artifacts

6.3.1. If your implementing project is not in the same package as the Web service files then it must be imported. If you omitted the package argument then import using the folder structure created by wsimport, this structure is usually the inverse of the webservice URL as per the Java Language Specification.

Example: Package addressrightsvc

                Import addressrightsvc.*;

Example: Package argument omitted

                Import com.simplicitycrm.services.addressright.*;

6.3.2. To operate on the web service requires an instance of the interface, which is instantiated using the get method of the Service Factory class.

Example: Instantiating the webservice

public class Main{

                public AddressRightSvc serviceFactory;

                public AddressRightSvcSoap myService;

                public void CreateService(){

                                serviceFactory = new AddressRightSvc();

                                 myService = serviceFactory.getAddressRightSvcSoap();

                }

}

6.3.3. The interface can then be used to call methods on the web service as normal.

Example: Using the webservice

                public void LoginLogout(){

                                String loginresult = myService.login("key", "username", "password");

                                 myService.logout(loginresult);

                }

6.4.    Within an IDE

           Required Tools

• Netbeans 5.5 Java IDE.

6.4.1.    Open Net Beans

6.4.2.    Click on the File menu and select New Project

6.4.3.    Select Java Application and click next