GB Portal Web Service Migration to Loqate's Address Capture
- Purpose of this guide
- What is GB Web Portal Service?
- What is Loqate's address verification?
- Your current integration
- Packages
- GB Web Portal and Loqate differences
- Further reading
Purpose of this guide
The purpose of this guide is to assist you with migrating from the GB Web Portal Web Service to Loqate's address verification.
What is GB Web Portal Web Service?
The GB Web Portal Web Service comprises a number of packages accessed via Web Services e.g. address validation, mobile, email Validation. These are typically accessed via the following endpoints:
https://webportal.gb.co.uk/GBPortalWS/GBPortalWS_8a.asmx
https://webportal.gb.co.uk/GBPortalWS/GBPortalWSDirect.asmx
What is Loqate's address verification?
Loqate’s address verification tool is the flagship web service solution of GBG for validating and verifying addresses at the point of capture. The web service uses real-time address lookups against a comprehensive dataset that is updated regularly in the cloud, eliminating the need for internal maintenance and supervision of a production server.
Your current integration
The GB Portal API is accessed via SOAP XML calls to the service, and XML responses are returned. This is typically via server side Java or C#. Migrating to Loqate's address verification will provide more options, both client- and server-side. See the API documentation for more information:
Packages
You'll find this guide useful if you are using the following packages:
- WS-AcceleratorAddress
- WS-AcceleratorDataValidation
Please contact your Account Manager if you are using any of the below packages:
- WS-AcceleratorNames
- WS-AddressBasePremiumBusiness
- WS-AcceleratorAddressPMD
- WS-AcceleratorTelephone
This migration will also give you the opportunity to revisit data requirements, including available data sets such as Multiple Residence, Not Yet Built and AddressBase, plus a variety of validation services.
How do I find out what package I'm using?
The package name is passed as part of the request for Pinpoint, Find and List as the field labelled szPackageName
What are the differences between the GB Portal and Loqate's address verification services?
API calls
When using GB Portal you need to deploy SOAP XML requests. Loqate Capture is significantly more flexible and permits a variety of integration options such as SOAP XML and REST JSON, but can also be deployed client-side e.g. via JavaScript.
We recommend reading the API documentation for full details.
Searching
With Loqate, a user will be presented with suggestions as they type into an input field. This presents the user with real-time suggestions that get more accurate as more characters are entered into the input.
The following is a list of the GB Portal requests you'll likely be using, and the equivalent Loqate request.
GB Portal | Loqate |
---|---|
Pinpoint - requires a postcode and a premise Example request differences |
Find - searches on a range of address parts; followed by Retrieve to get fully formatted address details |
Find - typically used where a postcode is unknown (e.g. GB Group plc, Chester) Example request differences |
Find - as above |
CreateAuthenticatesSession - where the direct service isn't used | No Loqate equivalent |
List – More commonly used for Data Validation services | No Loqate equivalent |
Info – To establish version information | No Loqate equivalent |
Pinpoint differences
A typical GB Portal request:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:gbp="http://webportal.gb.co.uk/GBPortal"> <soap:Header/> <soap:Body> <gbp:Pinpoint> <!--Optional:--> <gbp:szPackageName>WS-AcceleratorAddress</gbp:szPackageName> <!--Optional:--> <gbp:szUserName>USERNAME</gbp:szUserName> <!--Optional:--> <gbp:szPassword>*********</gbp:szPassword> <!--Optional:--> <gbp:szPostcode>CH4 9GB</gbp:szPostcode> <!--Optional:--> <gbp:szPremise></gbp:szPremise> <!--Optional:--> <gbp:szAddressFormat>Three address lines, town, county and postcode</gbp:szAddressFormat> <!--Optional:--> <gbp:szRelatedTypes>?</gbp:szRelatedTypes> <gbp:nOffset>0</gbp:nOffset> <gbp:nMaxReturns>200</gbp:nMaxReturns> </gbp:Pinpoint> </soap:Body> </soap:Envelope>
A typical Loqate request:
<?xml version="1.0" encoding="utf-8" ?> <soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <Find xmlns="https://api.addressy.com/"> <Key>AA11-AA11-AA11-AA11</Key> <Text>CH4 9GB</Text> <IsMiddleware>True</IsMiddleware> <Container>GB|RM|ENG|3DA-WR5</Container> <Origin>52.182,-2.222</Origin> <Countries>GB,US,CA</Countries> <Limit>10</Limit> <Language /> </Find> </soap:Body> </soap:Envelope>
Find differences
A typical GB Poral request:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:gbp="http://webportal.gb.co.uk/GBPortal"> <soap:Header/> <soap:Body> <gbp:Find> <!--Optional:--> <gbp:szPackageName>WS-AcceleratorAddress</gbp:szPackageName> <!--Optional:--> <gbp:szUserName>USERNAME</gbp:szUserName> <!--Optional:--> <gbp:szPassword>*********</gbp:szPassword> <gbp:structSearchCriteria> <!--Optional:--> <gbp:Text>?</gbp:Text> <!--Optional:--> <gbp:Items> <!--Zero or more repetitions:--> <gbp:AcceleratorItem> <!--Optional:--> <gbp:Key>ORGN</gbp:Key> <gbp:Value>GB Group plc</gbp:Value> <gbp:Key>TOWN</gbp:Key> <gbp:Value>Chester</gbp:Value> </gbp:AcceleratorItem> </gbp:Items> </gbp:structSearchCriteria> <!--Optional:--> <gbp:szAddressFormat>Five address lines and postcode</gbp:szAddressFormat> <!--Optional:--> <gbp:szRelatedTypes>?</gbp:szRelatedTypes> <!--Optional:--> <gbp:szAddressLevel>PREMISE</gbp:szAddressLevel> <gbp:nOffset>0</gbp:nOffset> <gbp:nMaxReturns>1000</gbp:nMaxReturns> </gbp:Find> </soap:Body> </soap:Envelope>
A typical Loqate request
<?xml version="1.0" encoding="utf-8" ?> <soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <Find xmlns="https://api.addressy.com/"> <Key>AA11-AA11-AA11-AA11</Key> <Text>CH4 9GB</Text> <IsMiddleware>True</IsMiddleware> <Container>GB|RM|ENG|3DA-WR5</Container> <Origin>52.182,-2.222</Origin> <Countries>GB,US,CA</Countries> <Limit>10</Limit> <Language /> </Find> </soap:Body> </soap:Envelope>