DataTools Tech Discovery
Predictive Address Implementation
DataTools Discovery
Predictive Address Implementation
Watch as Kezhal and Nate take a look into Kleber Predictive address and prepare you for your next Kleber implementation.
We recommend watching the video first before reviewing the notes below.
Each of the links below will provide further information on the Kleber method, the parameters required, the output fields returned and how to make the call using REST or SOAP. All Kleber calls are through the same endpoint. The Method parameter decides which Kleber method is being called.
Address Capture
As Kleber has different Search, Retrieve and Repair methods for different countries we suggest having a dropdown box as the first address question where a user can select the country of the address they are entering. This box can have ‘Australia’ or another country as the default based on the site entered or use a GEO IP location service to automatically default the country to the user location. This way the address capture user assistance feature mention below is activated for the correct country, preventing possible user confusion.
Australian Address Capture
Use the DataTools.Capture.Address.Predictive.AuPaf.SearchAddress method to present address suggestions as a user types. When the user selects one of the addresses from the suggestions list use the DataTools.Capture.Address.Predictive.AuPaf.RetrieveAddress method to return the full address details. Note: The Search method must always be used in conjunction with the Retrieve method to comply with the data licensing conditions.
For Australian addresses that were not successfully selected from the suggestions list
Implement the DataTools.Repair.Address.AuPaf.RepairAddress method after the full address has been entered manually. This method will accept a full address and return a single correct address, verified, formatted and with minor repairs where possible.
If the method returns a ‘Match Type’ of ‘0’ it has successfully been able to return a properly formatted, validated address. ‘Match Type’ of ‘18’ also return a properly formatted address but be aware that these addresses have only been matched to the building address, not to the unit/apartment number. ‘Match Type’ of ‘9’ ‘Phantom Primary Point’ doesn’t return an address. The address exists but it requires a unit number to match. To increase your data’s accuracy, you could implement a message to the customer for this Match Type result of ‘9’ requesting the user to add a unit number to the address.
The ’Field Changes’ field will identify any changes that were required to make the address correct, in case you want to add a user prompt to confirm these changes. This method only returns addresses where it is 100% certain of its result.
Test address: 5 Sesil St, Marylands NSW
Example of a user prompt where an address has been successfully found by Repair and Field Changes were made.
Example message where repair was unable to find an address
Other consideration
In a public facing implementation, we recommend that no orders/registration should be rejected, or additional friction be added to the user experience because of an invalid address. Instead, where Kleber cannot find a valid address, records should simply be flagged for further investigation after the record has been received. Also, even though the Kleber webservice should always be available it’s good practice to implement it in such a way that if the webservice was unavailable it doesn’t impact the websites order taking ability.
Alternative Australian Localities
Australia Post provides a list of acceptable bordering localities for various suburbs throughout Australia. This will allow for more matches to be made on streets which are located on the boundaries of suburbs and are often represented as being over the border from their gazetted location. Postal lodgement system, for example eParcel and Shippit will often reject these valid alternatives and insist on the gazetted locality being used. If you are experiencing this problem use the data from the AltLocality, AltState and AltPostcode fields in place of the Locality, State and Postcode fields.
Output field format for printing an Australian address
[BuildingName]
[AddressLine]
[Locality] [State] [Postcode]
[BuildingName] appears occasionally. If available use it as Address Line 1.
[AddressLine] is always returned. If a [BuildingName] is available make [AddressLine], Address Line 2.
[Locality] also know as Suburb, City or Town is often stored separately in a database. It makes up the first component of the last address line. It is required to be printed in uppercase for mail.
[State] also often stored separately field in a database. Represented by a 2 or 3 character abbreviation eg NSW, SA. It makes up the second component of the last address line. It is always printed be printed in uppercase.
[Postcode] similar to a Zip code in the US. It is always 4 digits long. Be aware that some postcodes have a leading zero. Eg 0801. It makes up the last component of the last address line
Address Capture for other countries
Below is a list of the Search, Retrieve and Full address methods for other countries. Implement these methods similar to what has been mentioned above for Australian address capture.
Protecting your Kleber Request Key
Please make sure you keep you Kleber Request Key safe. Never have the key visible in client-side code. This key in the wrong hands can lead to fraudulent transaction being charged to your account.
In the case where the a call is required client side, call the DataTools.Security.GenerateTemporaryRequestKey method server side on page load to generate a Temporary Request Key. Note: This method may return non alphanumeric characters in the TemporaryRequestKey. Use a Uri Encoding method to encode the Temporary Request Key before sending it through to a Kleber call. For example in Java Script …=> encodeURIComponent(TemporaryRequestKey).
Also keep in mind that the Temporary Request Key will expire and could expire while the user is accessing the page where a user has spent an extended amount of time on the page. This error can be trapped by checking the DtReponse ErrorMessage for “Temporary Request Key has expired”. A process should be implemented to make an additional server-side call to refresh the Temporary Request Key when this occurs.
Other methods
For your reference here are the other commonly used Kleber methods mention in the video.
Email validation – use DataTools.Verify.Email.BriteVerify.VerifyEmail to verify if an email address is real.
Phone number validation – use DataTools.Verify.PhoneNumber.Equifax.VerifyPhoneNumberIsConnected to verify if an Australian or New Zealand phone number is connected and use
DataTools.Verify.PhoneNumber.NumVerify.VerifyPhoneNumber to verify the format of all international phone numbers.
Site Review
Once your integration is complete, we’d like to offer you a complementary review. This process is quite simple and gives you the peace of mind that the Kleber integration has been done in the best possible way. All you will need to do is give DataTools access to the pages in your application where Kleber has been integrated. DataTools will then overlook the pages and make sure the appropriate Kleber calls are being made at the right times. DataTools will then give you feedback where any improvements can be made, if any.
Need Help
Please feel free to contact DataTools Support if you have any questions or require any assistance.
