GBG Developers

Guides   |   Using the Address Service

Using the Address Service

The Address service can be used for purposes such as rapidly entering an address manually. A typical scenario would be to allow the mobile user to begin typing in the postcode, and a list of addresses would be displayed as they type. From the list of addresses, the user could select one and the SDK would then query the GBG Identity Solution to retrieve the full address details to fully populate all fields in a form.

The Address Service portion of the SDK therefore is used in two stages. The first stage can be used as the postcode is typed. Here’s an example where the postcode text to be queried is sent as a parameter in the find method.

First, create an instance of GBGAddressLookupService as shown here:

private lazy var addressService = GBGAddressLookupService()

Next, buid a GBGFindAddressRequest object and pass in the search term.

let text = "SW2 223T"
let findAddressRequest = GBGFindAddressRequest()
                                .withCountries("GB")
                                .withText(text)
                                .withLanguage("en")
                                .withLimit(10)

To perform a lookup for possible matching addresses, call the find method and pass in the GBGFindAddressRequest object. The returned result contains a list of possible addresses, each with an identifier. The example code below will display the results as text output to the console.

self?.addressService.find(findAddressRequest, success: { result in
    self?.delegate?.didFind(result?.body, forCellAt: indexPath)
    print("address service, find() success: \(result?.body)")
}, failure: { error in
    if let error = error as? GBGErrorResponse<String>,
        error.response != nil {
        print("address service, error in find! \(error)")
    }
})

In normal use, the find method will be called as many times as needed, as the user types in the search box. The returned results would be listed by the application, so that the user can select one of them to accelerate their address completion.

The screenshot here shows an example mobile application where the user has begun typing in a postcode, and the first stage of the Address Service was executed. The returned list of addresses is displayed for the user to select from.

Once the user has chosen one of the entries, the second stage of the Address Service can be used. This second stage will submit the chosen id value to the GBG Identity Solution and return the complete address.

self.addressService.retrieveAddress(with: address.id ?? "", success: { retrievedAddress in
    if let retrievedAddress = retrievedAddress?.body?.first {
        val addressLine = retrievedAddress.premise + " " + retrievedAddress.premise + " " + retrievedAddress.locality
                      + " " + retrievedAddress.postalCode + " " + retrievedAddress.pcaFields?.countryIso2
        self.showPopup(message: "address retrieve successful "+addressLine)

The example above will just print out some of the information from the response, however far granular detail is returned.

You can use the retrieved address to build a GBGPersonAddress object (see Using the Verify People Service) as shown here:

let personAddress =  GBGPersonAddress()
    .withPremise(retrievedAddress.premise)
    .withThoroughfare(retrievedAddress.thoroughfare)
    .withLocality(retrievedAddress.locality)
    .withPostalCode(retrievedAddress.postalCode)
    .withCountry(retrievedAddress.pcaFields?.countryIso2)

person.withAddresses([GBGPersonAddresses().withAddress(personAddress).withType("CURRENT")])

Once you have done that, the Verify People service can be used to verify the person using this retrieved address.