Loqate | A GBG Solution

Address Web Service Integration Guide

This guide explains how to access GBGroup's web service products using their Identity Management Platform (IdM), available via SOAP web services. The document provides a general description of the available functionality along with a definition of the corresponding interfaces used to access different datasets and services.

The fundamentals of integrating with the service are described here: Integration Fundamentals

The main body of this document gives product specific details regarding the use of the Address Web Service products via IdM.

Please note: Wherever <LatestWSDLVersion> is shown in Example Code below, please replace this with GlobalServices21a.wsdl.

Address Web Service Product Information

The UK Address web service products are available via the Identity Management ExecuteCapture web service method.

Basic Name and Address Capture

Method: ExecuteCapture

The ExecuteCapture method is used to access the GBG Customer Registration products and services by invoking the corresponding profile.

Input Details

Type: ExecuteCaptureRequest

Field Name	Type	Description
securityHeader	SecurityHeader	The username and authentication token used to access the system.
profileRequest	ProfileRequestCapture	Details of the request

The SecurityHeader structure holds security data to access products and services in the IdM Platform.

The ProfileRequestCapture structure contains the criteria to identify the target product being called. In the profileRequest element, the profileGuid should be specified as:

Profile	GUID
Address Premise	6C49BC44-C104-41b2-BB62-2AE45A09DD54
Address Street Level	C6356DD8-1CBA-4371-BE94-D5E08F1C777E

Output Details

The ExecuteCaptureResponse structure contains the results of an capture query. The response contains the authentication token to be passed into subsequent web service calls. The latest authentication token should always be passed into service calls.

Type: ExecuteCaptureResponse

Field Name	Type	Description
securityHeaderResponse	SecurityHeaderResponse	Authentication information for subsequent calls
transactionGuid	String	Unique transaction reference
profileResponse	ProfileResponse	Response to the query

The ProfileResponse structure contains the results for an operation performed against a profile.

Type: ProfileResponse

Field Name	Type	Description
Field Name	Type	Description
ProfileResponseHeader	ProfileResponseHeader	Contains the Profile information for the results of the query
profileResponses	ProfileResponseDetails	Response data to the query

The ProfileResponseDetails structure contains the results for an operation performed against a product/data service in the Profile. It is possible to call multiple products in a single profile; in this case there will be multiple ProfileResponseDetails structures, one for each product.

Type: ProfileResponseDetails

Field Name	Type	Description
transactionGuid	String	Unique transaction identifier for the component e.g. Address Lookup component
componentName	String	Name of the component
componentStatus	Enum	SUCCESS, FAILURE, INSUFFICIENTCRITERIA, NA
componentAction	String	Component Action
responseType	Enum	CAPTURE
invoice	DataLicenceInvoice	List of charges for the query
captureResponse	CaptureResponse	Data from a component returning data e.g. Address lookup data
validateResponse	ValidateResponse	Data from a component returning validation responses e.g. Telephone Validation service

The CaptureResponse structure contains response records for a particular component/product. The data is held in a standard format across all products. The data structure is a flexible set of arrays designed to represent the data in a way that reflects the records in context of the search. The arrangement of the data will depend on the product in question. For more information on the layout of the response data please refer to the corresponding product documentation.

Type: CaptureResponse

Field Name	Type	Description
resultStatus	Enum	NA, INSUFFICIENTCRITERIA, NONE, SINGLE, MULTIPLE, PICKLIST, VERIFY
recordsReturned	Int	Number individual of records returned e.g. number of addresses
moreData	Boolean	More data on the server
totalRecordCount	Int	Total records from the query
totalPages	Int	Pagination - Total pages
responseCount	Int	Number of groups of responses returned
response	CaptureResponseData	Response data

The ValidateResponse structure contains response records for a particular component/product. The data is held in a standard format across all products. For more information on the layout of the response data please refer to the corresponding product documentation.

Type: ValidateResponse

Field Name	Type	Description
resultStatus	Enum	NA, INSUFFICIENTCRITERIA, NONE, SINGLE, MULTIPLE, PICKLIST, VERIFY
recordsReturned	Int	Number individual of records returned e.g. number of addresses
responseCount	Int	Number of group of response returned
response	ValidateResponseData	Response data

Sample XML

Sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:mes="http://gbworld.gb.co.uk/idm-globalservices/messages/<LatestWSDLVersion>/" xmlns:head="http://gbworld.gb.co.uk/types/header/"
       xmlns:req="http://gbworld.gb.co.uk/types/core/request/" xmlns:data="http://gbworld.gb.co.uk/types/core/data/" 
       xmlns:xsi="xsi">
      <soapenv:Header/>
      <soapenv:Body>
       <mes:ExecuteCaptureRequest>
        <mes:securityHeader>
         <head:username>user@domain.com</head:username>
        </mes:securityHeader>
        <mes:profileRequest>
         <req:customerReference>Test</req:customerReference>
         <req:profileGuid>6C49BC44-C104-41b2-BB62-2AE45A09DD54</req:profileGuid>
         <req:requestData>
            <req:address>
             <data:town>CHESTER</data:town>
             <data:postCode>CH49GB</data:postCode>
             <data:building>*</data:building>
            </req:address>
            <req:filters/>
            <req:options>
             <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
             <req:relatedDataItems tmp="?">
              <!--Zero or more repetitions:-->
              <data:key>UBID</data:key>
             </req:relatedDataItems>
             <req:offset>0</req:offset>
             <req:maxReturn>100</req:maxReturn>
             <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
             <req:casing>MIXED</req:casing>
            </req:options>
            <req:additionalData/>
         </req:requestData>
        </mes:profileRequest>
       </mes:ExecuteCaptureRequest>
      </soapenv:Body>
   </soapenv:Envelope>

{
    "customerReference": "Test",
    "profileGuid": "6C49BC44-C104-41b2-BB62-2AE45A09DD54",
    "configurationId": "1",
    "requestData": {
      "address": {
        "town": "CHESTER",
        "postCode": "CH49GB",
        "building": "*"
      },
      "options": {
        "addressEnvelopeFormat": "A4P",
        "relatedDataItems":{"key":["UBID"]},
        "offset": "0",
        "maxReturn": "100",
        "addressSearchLevel": "PREMISE",
        "casing": "MIXED"
      }
    }
}

Sample response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
              <SOAP-ENV:Header/>
              <SOAP-ENV:Body>
               <mes:ExecuteCaptureResponse xmlns:mes="http://gbworld.gb.co.uk/idm-globalservices/messages/<LatestWSDLVersion>/"
                 xmlns:alu="http://gbworld.gb.co.uk/types/core/request/alu/" xmlns:billingTypes="http://gbworld.gb.co.uk/types/billing/" 
                 xmlns:common="http://gbworld.gb.co.uk/types/common/" xmlns:comp="http://gbworld.gb.co.uk/types/component/" 
                 xmlns:data="http://gbworld.gb.co.uk/types/core/data/" xmlns:datatypes="http://gbworld.gb.co.uk/types/datatypes/" 
                 xmlns:faults="http://gbworld.gb.co.uk/types/faults/" xmlns:head="http://gbworld.gb.co.uk/types/header/" 
                 xmlns:prop="http://gbworld.gb.co.uk/idm-core/component/properties/" 
                 xmlns:req="http://gbworld.gb.co.uk/types/core/request/" 
                 xmlns:ver="http://gbworld.gb.co.uk/types/core/request/verify/">
                <mes:securityHeader>
                 <head:authenticationToken xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                 <head:authenticationTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                   2012-12-17T20:27:21.879Z</head:authenticationTime>
                 <head:sessionExpiryTime xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                </mes:securityHeader>
                <mes:transactionGuid>0E64D43B-378D-40CB-9DD9-89C41A4D9A8A</mes:transactionGuid>
                <mes:profileResponse>
                 <req:profileHeader>
                    <req:profileGuid>6C49BC44-C104-41b2-BB62-2AE45A09DD54</req:profileGuid>
                    <req:profileName>Address Lookup - Fixed Field</req:profileName>
                    <req:transactionGuid>0E64D43B-378D-40CB-9DD9-89C41A4D9A8A</req:transactionGuid>
                    <req:transactionTimeStamp>2012-12-17T20:27:21.610Z</req:transactionTimeStamp>
                    <req:profileStatus>SUCCESS</req:profileStatus>
                 </req:profileHeader>
                 <req:profileResponses>
                    <req:profileResponse>
                     <req:transactionGuid>86CA24C8-51CA-4E09-8785-473693BD3147</req:transactionGuid>
                     <req:componentName>NR Address Lookup</req:componentName>
                     <req:componentStatus>SUCCESS</req:componentStatus>
                     <req:componentAction>NR</req:componentAction>
                     <req:responseType>CAPTURE</req:responseType>
                     <req:notes>[]</req:notes>
                     <req:invoice>
                      <req:invoiceList>
                       <req:invoiceGuid>503656F9-2BB3-4908-9965-36456F77B024</req:invoiceGuid>
                       <req:billingInformationGuid>376B7A97-C25B-4d14-8AB1-64CD874AEECE</req:billingInformationGuid>
                       <req:billingPoints>1</req:billingPoints>
                       <req:dataSetInvoices>
                          <req:dataSetCode>PAF</req:dataSetCode>
                          <req:billingPoints>1</req:billingPoints>
                          <req:recordsReturned>1</req:recordsReturned>
                          <req:dataLicenceGuid>376B7A97-C25B-4d14-8AB1-64CD874AEECE</req:dataLicenceGuid>
                       </req:dataSetInvoices>
                      </req:invoiceList>
                     </req:invoice>
                     <req:captureResponse>
                      <req:resultStatus>SINGLE</req:resultStatus>
                      <req:recordsReturned>1</req:recordsReturned>
                      <req:moreData>false</req:moreData>
                      <req:totalRecordCount>1</req:totalRecordCount>
                      <req:totalPages>1</req:totalPages>
                      <req:responseCount>1</req:responseCount>
                      <req:response>
                       <req:addresses>
                          <data:address>
                           <data:organisation>GB GROUP PLC</data:organisation>
                           <data:street>HERONS WAY</data:street>
                           <data:town>CHESTER</data:town>
                           <data:postCode>CH4 9GB</data:postCode>
                           <data:locality>CHESTER BUSINESS PARK</data:locality>
                           <data:buildingName>THE FOUNDATION</data:buildingName>
                           <data:stateRegion>CHESHIRE</data:stateRegion>
                           <data:dpsZipPlus>1AR</data:dpsZipPlus>
                           <data:formattedAddress>Gb Group Plc,The Foundation,Herons Way, Chester Business Park,Chester Cheshire,CH4 9GB</data:formattedAddress>                            <data:additionalItems>
                            <data:item>
                             <data:key>UBID</data:key>
                             <data:value>CH049GB11A</data:value>
                            </data:item>
                           </data:additionalItems>
                           <data:persons/>
                          </data:address>
                       </req:addresses>
                      </req:response>
                     </req:captureResponse>
                    </req:profileResponse>
                 </req:profileResponses>
                </mes:profileResponse>
               </mes:ExecuteCaptureResponse>
              </SOAP-ENV:Body>
           </SOAP-ENV:Envelope>

{
   "profileHeader":    {
      "profileGuid": "C6356DD8-1CBA-4371-BE94-D5E08F1C777E",
      "profileName": "Address Street Level - Web Service",
      "transactionGuid": "5D4B9677-A109-40B2-A35B-C92E5C70168F",
      "transactionTimeStamp": 1433332665130,
      "profileStatus": "SUCCESS",
      "remarks": null
   },
   "profileResponseDetails": [   {
      "transactionGuid": "8E9CE0BD-70C8-482F-9B74-9472E32F9F7A",
      "componentName": "Accelerator Address",
      "componentStatus": "SUCCESS",
      "componentAction": "NR",
      "responseType": "CAPTURE",
      "notes": "[]",
      "invoice":       {
         "invoiceList": [         {
            "invoiceGuid": "B2DAF313-A4C6-49E6-83D0-F37B820A3E7A",
            "billingInformationGuid": "88176B02-9CE0-431d-8913-43A138AF64B8",
            "dataLicenceDescription": null,
            "billingPoints": 1,
            "creditsUsed": 1,
            "dataSetInvoices": [            {
               "dataSetCode": "PAF_PARTIAL",
               "billingPoints": 1,
               "recordsReturned": 1,
               "dataLicenceGuid": "88176B02-9CE0-431d-8913-43A138AF64B8"
            }]
         }],
         "tmp": null
      },
      "captureResponse":       {
         "resultStatus": "SINGLE",
         "resultStatusDetail": null,
         "recordsReturned": 1,
         "moreData": false,
         "totalRecordCount": 1,
         "totalPages": 1,
         "matchScore": 0,
         "matchLevel": null,
         "outputStatus": null,
         "fieldStatus": null,
         "responseCount": 1,
         "response": [         {
            "input": null,
            "address": [            {
               "organisation": null,
               "street": "Kingsfield Court",
               "town": "CHESTER",
               "postCode": "CH4 9GB",
               "locality": "Chester Business Park",
               "addPoint": null,
               "department": null,
               "subBuilding": null,
               "buildingNumber": null,
               "buildingName": null,
               "buildingGroup": null,
               "poBox": null,
               "subStreet": null,
               "subLocality": null,
               "stateRegion": "Cheshire",
               "subAdministrativeArea": null,
               "administrativeArea": null,
               "superAdministrativeArea": null,
               "countryCode": "GBR",
               "countryName": null,
               "dpsZipPlus": null,
               "formattedAddress": "Gb Group Plc,The Foundation,Herons Way, Chester Business Park,Chester Cheshire,CH4 9GB",
               "geographicInformation":                {
                  "easting": "340000",
                  "northing": "363100",
                  "latitude": " 53.161350",
                  "longitude": " -2.897495",
                  "status": null,
                  "level": null,
                  "distance": null,
                  "radius": null
               },
               "additionalItems":                {
                  "item": [],
                  "tmp": null
               },
               "groupedAdditionalItems": [],
               "persons":                {
                  "person": [],
                  "tmp": null
               },
               "uprn": null,
               "lpi": null,
               "blpu": null,
               "streetDescriptor": null,
               "streetInformation": null,
               "companyInformation": null,
               "classification": null,
               "osAl2Toid": null,
               "osItnToid": null,
               "osTopoToid": null,
               "voaCtRecord": null,
               "voaNdrRecord": null,
               "apOSAPR": null,
               "rmUDPRN": null,
               "utilitiesInformation": null
            }],
            "relatedData": null,
            "groupedRelatedData": []
         }]
      },
      "validateResponse": null,
      "verifyResponse": null,
      "traceResponse": null
   }]
}

Address Capture - Search Criteria

The address search criteria should be entered into the IdmDataSearchAddress data structure, which is located within the input details as follows:

ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → IdmDataSearchAddress

Radius Search Criteria

Address Web Service supports radius searching, where a match is made for premises within a specified radius of a given point. To trigger a radius search values must be provided in the IdmDataGeographic structure of the search address. The easting and northing values should be specified to 5-digit accuracy.

Additional Search Criteria

Additional information can be searched upon by providing the key value pairs specified below to the IdmDataSearchAddress.additionalItems property. For example, if you require to search on Royal Mail Mailsort code the key 'MSRN' and the mailsort value should be provided.

Below is a list of searchable related fields:

Key Mnemonic	Description
AKEY	17 Digit Addresskey
AREA	Local Authority Area Code
EAST	Easting
MSRN	New Mailsort
MSRO	Old Mailsort
NHSC	DHA Code
NRTH	Northing
PABR	Postal Address Book Region
WARD	Local Authority Ward Code

Below is a list of additional Royal Mail PAF specific searchable address elements:

Key Mnemonic	Description
BNAM	Building Name
DDLO	Double Dependant Locality
DEPT	Department
DPLO	Dependent Locality
DPTH	Dependent Thorofare

Sample Search XML

<req:address>
   <!--Optional:-->
   <data:organisation/>
   <data:street/>
   <data:town/>
   <data:postCode>CH49GB</data:postCode>
   <data:locality/>
   <data:subBuilding/>
   <data:building>GB House</data:building>
   <data:subLocality/>
   <data:stateRegion/>
   <data:countryCode>GBR</data:countryCode>
   <data:poBox/>
   <data:freeFormatAddress>CH49GB, GB*</data:freeFormatAddress>
   <data:geographicInformation>
      <data:easting/>
      <data:northing/>
      <data:latitude/>
      <data:longitude/>
      <data:radius>
         <data:unit/>
         <data:distance>0.0</data:distance>
      </data:radius>
   </data:geographicInformation>
   <data:additionalItems tmp="?">
      <data:item>
         <data:key/>
         <data:value/>
      </data:item>
   </data:additionalItems>
</req:address>

Additional Execution Options

Configuration options for the GB Address Web Service search can be set in the IdmRequestOptions structure located in the ProfileRequestCaptureData.optionsproperty.


		Extensible array of key value pairs for future additional conversation

Additional Return Data

Additional data can be returned for each address by providing one of the following values to the IdmRequestOption.relatedDataItems property (See section 2.2.3 for an example):

Key Mnemonic	Description
AKEY	17 Digit Addresskey
AREA	Local Authority Area Code
EAST	Easting
INCO	Incode Only
MSRN	New Mailsort
MSRO	Old Mailsort
NRTH	Northing
OUTC	Outcode Only
PABR	Postal Address Book Region
WARD	Local Authority Ward Code

Envelope Format

Address web Service provides the option to return each address as it would appear on an envelope. The IdmRequestOptions.addressEnvelopeFormat property allows you to specify how this should data should be formatted. The following are valid configuration options:

Format Code	Description
A4P	Four address lines and postcode
A5P	Five address lines and postcode
A6P	Six address lines and postcode
A2TCP	Two address lines, town, county and postcode
A3TCP	Three address lines, town, county and postcode
A4TCP	Four address lines, town, county and postcode
NA4P	Name, four address lines and postcode
NA5P	Name, five address lines and postcode
NA6P	Name, six address lines and postcode
NA2TCP	Name, two address lines, town, county and postcode
NA3TCP	Name, three address lines, town, county and postcode
NA4TCP	Name, four address lines, town, county and postcode
A4P-B	Four address lines without business
A4TCP-B	Four address lines, town, county and postcode without business
PAF	All address elements

Sample Options XML

<req:options>
  <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
  <req:relatedDataItems tmp="?">
     <data:key>UBID</data:key>
  </req:relatedDataItems>
  <req:offset>0</req:offset>
  <req:maxReturn>100</req:maxReturn>
  <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
  <req:casing>MIXED</req:casing>
</req:options>

Output Format

The results of the Matchcode UK Address Web Service search are returned in a ProfileResponseDetails structure with a ProfileResponseDetail.responseType of 'CAPTURE'.

The ProfileResponseDetails structure contains a single CaptureResponse data structure which holds an array of IdmDataAddress records containing the returned address data.

ExecuteCaptureResponse > ProfileResponse [0] > ProfileResponseDetails [0] > CaptureResponse > CaptureResponseData > IdmDataAddress [n]

Sample Output XML

<req:response>
  <req:addresses>
     <data:address>
        <data:organisation>GB GROUP PLC</data:organisation>
        <data:street>KINGSFIELD COURT</data:street>
        <data:town>CHESTER</data:town>
        <data:postCode>CH4 9GB</data:postCode>
        <data:locality>CHESTER BUSINESS PARK</data:locality>
        <data:buildingName>GB HOUSE</data:buildingName>
        <data:stateRegion>CHESHIRE</data:stateRegion>
        <data:dpsZipPlus>1AR</data:dpsZipPlus>
        <data:formattedAddress>GB Group Plc,GB House  Kingsfield Court,Chester Business Park,CHESTER Cheshire,CH4 9GB</data:formattedAddress>
        <data:additionalItems>
           <data:item>
              <data:key>UBID</data:key>
              <data:value>CH049GB11A</data:value>
           </data:item>
        </data:additionalItems>
        <data:persons/>
     </data:address>
  </req:addresses>
</req:response>

IdM to Royal Mail PAF

The IdM web services provide the address format in a generic international format. The GB Address Web Service product allows address searching capability on UK based addresses. The mapping between the generic international address structure of IdM web service and the Royal Mail Postal Address File (PAF) is detailed below:

Data Mapping: IdmDataSearchAddress → Royal Mail PAF → IdmDataAddress

Input Field: IdmDataSearchAddress	PAF Field	PAF Field Code	Output Field: IdmDataAddress
organisation	Organisation	ORGN	organisation
department	Department	DEPT	department
subBuilding	Sub Building	SUBB	subBuilding
building^*	Building Name	BNAM	buildingName
building^*	Building Number	BNUM	buildingNumber
poBox	PO Box	POBX	poBox
street^*	Thorofare	THOR	street
street^*	Dependent Thorofare	DPTH	subStreet
locality^*	Dependent Locality	DPLO	locality
locality^*	Double Dependant Locality	DDLO	sublocality
town	Post Town	TOWN	town
stateRegion	County	CNTY	stateRegion
countryCode	N/A	N/A	countryCode
postCode	Postal Code	PCOD	postCode

^* Composite fields - Composite input fields offer advanced searching capabilities by searching against multiple target fields. e.g.locality - Searches against PAF Dependant Locality, Double Dependant Locality and PostTown.

Data Paging Additional Records

If the number of records available from a GB Address Web Service search is greater than the specified MaxRecords value provided in the options then that additional data can be acquired through paging. To retrieve the next page of records the search should be submitted again with the offset increased to the start of the next page.

Response XML indicating more data:

<req:captureResponse>
  <req:resultStatus>MULTIPLE</req:resultStatus>
  <req:recordsReturned>5</req:recordsReturned>
  <!--Paging Information:-->
  <req:moreData>false</req:moreData>
  <req:totalRecordCount>1574</req:totalRecordCount>
  <req:totalPages>16</req:totalPages>

Search XML requesting more data:

<req:options>
  <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
  <req:relatedDataItems tmp="?">
    <data:key>UBID</data:key>
  </req:relatedDataItems>
 
  <!-- Pagination Information -->
  <req:offset>5</req:offset>
  <req:maxReturn>5</req:maxReturn>
 
  <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
  <req:casing>MIXED</req:casing>
</req:options>

Error Information

Information on possible error codes is given here: Error Code Information