Migrating to Address V2

Step by step guide to migrating to Address V2.

Introduction

This guide is written to assist upgrading to receive the benefits of using Address V2.

We have depreciated all api connections except Address V2. This is to enable us to better improve our services to you.

Address V2 separates concepts of:

Address Lookup (typeahead service ) and Address Validation (the validated data) into two defined endpoints.

1. Address Lookup - the typeahead service

   1. API endpoint: .../v2/address/find

2. Address Validation - the validated data package of the address

   1. API endpoint: .../v2/address/retrieve

Benefits of using Address V2

We have implemented many improvements into Address V2 that can assist in problems encountered and knowledge gained from previous versions of our address lookup product(s).

• No contractual changes. You've purchased address validation we continue to supply address validations through an improved service. We proto-rata transactions from V1 to V2 when putting migration in production.

• The service is faster reducing loads and tuning compute by separating find and retrieve api endpoints.

• Many issues with V1 have resolution features in V2 that is enables by changing your api requests. Within the migration we can address these to ensure you have the best solution for your changing business needs.

• V2/address/find enables us to better monitor performance of find and bring new features to find functionality to improve our goal of finding target addresses the fastest with the least keystrokes.

• V2/address/retrieve has the same response data package reducing effort to migrate.

• V2 Reduces billable transaction ambiguity. Using V2 understand what is a Find and what is a Retrieve (Transaction) is independently monitored.

• V1 is depreciated. We are reducing our effort in supporting this endpoint and investing that effort in improving V2. The less customers on V1 the faster we can bring improvements.

• Improves our information security protocols to keep you and us safer.

Migration Timeline

We have depreciated all api connections prior to Address V2. We in the process of scheduling turn-off dates from 2024 until 2025 depending on the service.

Implementing V2 usually fully completed within 2 weeks.

The response package is the same as V1 meaning much of the complex work is re-usable from your V1 implementation.

Migration Checklist:

• 1) Notify Loqate AU & NZ that you intent to migrate to V2. You will get access and support to migrate.

• 2) Read & share with developers Address V2 API documentation within this documentation Loqate Harmony API > API Specification > Address > Address Validation and Lookup. In particular, the difference between Find and Retrieve api endpoints.

• 3) Read & share with developers client and/or server side libraries to assist in implementing V2. If you need a library please ask as we have more than we publicly publish.

• 4) Book a pre-development meeting with our team and your team (if required) to answer any questions. Check the FAQ here we are updating it.

• 5) Develop and Test Address V2 within your development team.

• 6) Notify Loqate AU & NZ of intended switch date.

• 7) Implement to production

FAQ

Do I need to sign new contract?

No. Unless you have a very old contract or through migrating you need access to additional data.

What happens to my transaction limits?

Any transaction limit are pro-rata. We consider V2 another service to conduct address validations.

For example: You have purchased 240,000 transactions, you utilise 90,000 transactions with V1 you will have 150,000 left for V2.

Does it cost more?

No, usually once implemented it reduces your costs.

Has the Data changed?

Its the same and the response data is the same schema its migrating from Address V1 being https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address.

Having the same schema greatly reduces the effort of migration as your existing processes should remain unchanged.

What are the best fields to use in integrations?

You want to use Universal Response objects when integrating. This is likely new since your last integation.

See Best Practice guide on Address Field Mappings.