AddressBase Lite from Ordnance Survey is a Premium source of detailed address intelligence for both business and government. It is built through a combination of the Ordnance Survey’s own research, the LLPG (Council Data) and PAF (Postal Address File). It includes:
  • 40m records
  • Unique Property Reference Number (UPRN) - which remains constant for the entire lifecycle of all buidlings in the UK
  • Alternative, Historic and Provisional address versions for all buildings (linked via UPRN)

​
About This 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 Input Format section of the document gives product specific details regarding the use of the Matchcode AddressBase Premium Web Service products via IdM. The Matchcode AddressBase Premium service provides access to the AddressBase Premium data, in a similar manner to Matchcode UK Address searching (see Matchcode UK Address Integration Guide) The Matchcode AddressBase Premium web service products are available via the Identity Management ExecuteCapture web service method. Please note: Wherever (LatestWSDLVersion) is shown in Example Code below, please replace this with GlobalServices21a.wsdl.

​
Input Format

The ExecuteCapture method takes in a ExecuteCaptureRequest data structure, which contains all the information necessary to carry out the request. Type: ExecuteCaptureRequest
Field NameTypeDescription
securityHeaderSecurityHeaderThe username and authentication token used to access the system.
profileRequestProfileRequestCaptureDetails 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 and the search data for the product request. Within the profileRequest element, the profileGuid element should contain the GUID value listed below:
ProfileGUID
AddressBase LiteBCB96C1A-BC4C-4110-8A9E-A097B55380BB

​
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 → address

​
Alternative Search Criteria

Along with the standard address search criteria, this service supports address searching by one of the address identifiers listed below. This search criteria is specified by using the additionalItems property of the search address. To carry out a search with one of these identifiers, a key-value pair must be included in the additional items property, with the key being the identifier and the value being the search value. Only one identifier can be used in a search, if more than one are specified the others will be ignored. This alternative search criteria overrides the standard address search criteria, which will be ignored if a valid identifier is provided in the IDM request.
KeyDescription
UPRNUnique property reference number
RM_UDPRNRoyal Mail unique delivery point reference number

​
Additional Request Options

The additional search options, used for configuring options such as casing or transliteration of output results, can be set in the IdmRequestOptions structure located in the ProfileRequestCaptureData.options property.

​
Additional Return Data

Additional data can be returned, or excluded from being returned, for each address by providing one or more values in the IdmRequestOption.relatedDataItems property. For each value provided, the corresponding additional data is returned, and the corresponding additional data for all the values not provided are not returned. The following values are supported by this service.
Key MnemonicDescriptionReturned By Default
COUNTRYCODECountry codeYes
UDPRNPAF unique delivery point reference numberYes
RM_UDPRNRoyal Mail unique delivery point reference numberYes
POSTCODE_LOCATORPostcode LocatorYes
LPI_STATUSLPI Logical StatusYes
SAO_START_NUMBERSAO Start NumberYes
SAO_START_SUFFIXSAO Start SuffixYes
SAO_END_NUMBERSAO End NumberYes
SAO_END_SUFFIXSAO End SuffixYes
SAO_TEXTSAO TextYes
PAO_START_NUMBERPAO Start NumberYes
PAO_START_SUFFIXPAO Start SuffixYes
PAO_END_NUMBERPAO End NumberYes
PAO_END_SUFFIXPAO End SuffixYes
PAO_TEXTPAO TextYes
AREA_NAMEArea NameYes
ST_DESCRIPTIONStreet DescriptionYes
ST_LOCALITYStreet LocalityYes
ST_TOWNStreet TownYes
ST_ADMIN_AREAStreet Administrative AreaYes
ORG_ORGANISATIONOrganisation NameYes
ORG_LEGAL_NAMELegal NameYes
DPA_ORG_NAMEDPA OrganisationYes
DPA_DEP_NAMEDPA DepartmentYes
DPA_SUB_NAMEDPA Sub-BuildingYes
DPA_BLD_NAMEDPA Building NameYes
DPA_BLD_NODPA Building NumberYes
DPA_DEPTFARE_NAMEDPA Dependent ThoroughfareYes
DPA_TFARE_NAMEDPA ThoroughfareYes
DPA_DEPLOCDPA Double Dependent LocalityYes
DPA_LOCALITYDPA Dependent LocalityYes
DPA_POSTTOWNDPA Post TownYes
DPA_POSTCODEDPA PostcodeYes
DPA_CYM_DEPTFAREDPA Welsh Dependent ThoroughfareYes
DPA_CYM_TFAREDPA Welsh ThoroughfareYes
DPA_CYM_DEPLOCDPA Welsh Double Dependent LocalityYes
DPA_CYM_LOCALITYDPA Welsh Dependent LocalityYes
DPA_CYM_POSTTOWNDPA Welsh Post TownYes
DPA_POBOXDPA PO Box NumberYes
DPA_DPSDPA Delivery Point SuffixYes

​
Additional Request Datasets

Data from additional datasets can be enabled or disabled for an address search, by populating the ProfileRequestCaptureData.additionalData property with key-value pairs from the applicable list table below. To use a particular dataset, the user must be subscribed to the dataset. This information should be entered into the IdmDataArrayAdditionalData data structure, which is located within the input details as follows: ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → additionalData
KeyPossible ValuesDescription
LOC_INT”Yes” or “No”Request Location Intelligence information to be returned
PREMISE_GEOCODE”Yes” or “No”Request Premise Level Geocode information to be returned

​
Location Intelligence

The location intelligence dataset is detailed here.

​
Premise Level Geocodes

The premise level geocodes dataset is detailed here.

​
Address Filters

Addresses which have been found by the web service, which match a particular kind of address, can be filtered out from the search results by using the address filters functionality described here.

​
Output Format

The results of the Matchcode Names 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] Additional data from a search may be returned in the additionalItems or the groupedAdditionalItems of the IdmDataAddress.

​
Output Fields

Apart from the standard address fields, the following additional fields are returned by the service:
FieldRelated Data Item KeyLocation In Response
UDPRNUDPRNIdmDataAddress → uprn
RM_UDPRNRM_UDPRNIdmDataAddress → rmUDPRN
POSTCODE_LOCATORPOSTCODE_LOCATORIdmDataAddress → IdmDataBLPU → postcodeLocator
LPI_STATUSLPI_STATUSIdmDataAddress → IdmDataLPI → lpiLogicalStatus
SAO_START_NUMBERSAO_START_NUMBERIdmDataAddress → IdmDataLPI → saoStartNumber
SAO_START_SUFFIXSAO_START_SUFFIXIdmDataAddress → IdmDataLPI → saoStartSuffix
SAO_END_NUMBERSAO_END_NUMBERIdmDataAddress → IdmDataLPI → saoEndNumber
SAO_END_SUFFIXSAO_END_SUFFIXIdmDataAddress → IdmDataLPI → saoEndSuffix
SAO_TEXTSAO_TEXTIdmDataAddress → IdmDataLPI → saoText
PAO_START_NUMBERPAO_START_NUMBERIdmDataAddress → IdmDataLPI → paoStartNumber
PAO_START_SUFFIXPAO_START_SUFFIXIdmDataAddress → IdmDataLPI → paoStartSuffix
PAO_END_NUMBERPAO_END_NUMBERIdmDataAddress → IdmDataLPI → paoEndNumber
PAO_END_SUFFIXPAO_END_SUFFIXIdmDataAddress → IdmDataLPI → paoEndSuffix
PAO_TEXTPAO_TEXTIdmDataAddress → IdmDataLPI → paoText
AREA_NAMEAREA_NAMEIdmDataAddress → IdmDataLPI → areaName
ST_DESCRIPTIONST_DESCRIPTIONIdmDataAddress → IdmDataStreetDescriptor → streetDescription
ST_LOCALITYST_LOCALITYIdmDataAddress → IdmDataStreetDescriptor → locality
ST_TOWNST_TOWNIdmDataAddress → IdmDataStreetDescriptor → townName
ST_ADMIN_AREAST_ADMIN_AREAIdmDataAddress → IdmDataStreetDescriptor → administrativeArea
ORG_ORGANISATIONORG_ORGANISATIONIdmDataAddress → IdmDataCompanyInformation → organisationName
ORG_LEGAL_NAMEORG_LEGAL_NAMEIdmDataAddress → IdmDataCompanyInformation → legalOrganisationLegalName
DPA_ORG_NAMEDPA_ORG_NAMEIdmDataAddress → additionalItems → DPA_ORG_NAME
DPA_DEP_NAMEDPA_DEP_NAMEIdmDataAddress → additionalItems → DPA_DEP_NAME
DPA_SUB_NAMEDPA_SUB_NAMEIdmDataAddress → additionalItems → DPA_SUB_NAME
DPA_BLD_NAMEDPA_BLD_NAMEIdmDataAddress → additionalItems → DPA_BLD_NAME
DPA_BLD_NODPA_BLD_NOIdmDataAddress → additionalItems → DPA_BLD_NO
DPA_DEPTFARE_NAMEDPA_DEPTFARE_NAMEIdmDataAddress → additionalItems → DPA_DEPTFARE_NAME
DPA_TFARE_NAMEDPA_TFARE_NAMEIdmDataAddress → additionalItems → DPA_TFARE_NAME
DPA_DEPLOCDPA_DEPLOCIdmDataAddress → additionalItems → DPA_DEPLOC
DPA_LOCALITYDPA_LOCALITYIdmDataAddress → additionalItems → DPA_LOCALITY
DPA_POSTTOWNDPA_POSTTOWNIdmDataAddress → additionalItems → DPA_POSTTOWN
DPA_POSTCODEDPA_POSTCODEIdmDataAddress → additionalItems → DPA_POSTCODE
DPA_CYM_DEPTFAREDPA_CYM_DEPTFAREIdmDataAddress → welshSubStreet
DPA_CYM_TFAREDPA_CYM_TFAREIdmDataAddress → welshStreet
DPA_CYM_DEPLOCDPA_CYM_DEPLOCIdmDataAddress → welshSubLocality
DPA_CYM_LOCALITYDPA_CYM_LOCALITYIdmDataAddress → welshLocality
DPA_CYM_POSTTOWNDPA_CYM_POSTTOWNIdmDataAddress → welshTown
DPA_POBOXDPA_POBOXIdmDataAddress → additionalItems → DPA_POBOX
DPA_DPSDPA_DPSIdmDataAddress → additionalItems → DPA_DPS

​
Example Requests & Responses

​
Example Requests

The following example shows how to use the alternative search criteria mentioned previously, to to search for an address by its UPRN value.

​
SOAP

<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:a="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/">
    <soapenv:header/>
    <soapenv:body>
        <a:executecapturerequest>
            <a:securityheader>
                <head:authenticationtoken>C18AB65D-85A0-4C48-81A9-C5E23058C819</head:authenticationtoken>
                <head:username>CENSORED</head:username>
            </a:securityheader>
            <a:profilerequest>
                <req:customerreference>Sample ABL Lookup</req:customerreference>
                <req:profileguid>BCB96C1A-BC4C-4110-8A9E-A097B55380BB</req:profileguid>
                <req:configurationid>1</req:configurationid>
                <req:requestdata>
                    <req:address>
                        <data:additionalItems>
                            <data:item>
                                <data:key>UPRN</data:key>
                                <data:value>200000069805</data:value>
                                <!-- "Bank Of England,Threadneedle Street,London,EC2R 8AH" -->
                            </data:item>
                        </data:additionalItems>
                    </req:address>
                    <req:filters tmp="?"/>
                    <req:options>
                        <req:addressenvelopeformat>A4P</req:addressenvelopeformat>
                        <req:offset>0</req:offset>
                        <req:maxreturn>50</req:maxreturn>
                        <req:transliteration>NATIVE</req:transliteration>
                        <req:countrycodeformat>ISO3</req:countrycodeformat>
                    </req:options>
                    <req:additionaldata tmp="?"/>
                </req:requestdata>
            </a:profilerequest>
        </a:executecapturerequest>
    </soapenv:body>
</soapenv:envelope>

​
Example Responses

​
SOAP

<soap-env:envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:header/>
    <soap-env:body>
        <ns5:executecaptureresponse xmlns:ns5="http://gbworld.gb.co.uk/idm-globalservices/messages/(LatestWSDLVersion)/"
                                    xmlns:data="http://gbworld.gb.co.uk/types/core/data/"
                                    xmlns:head="http://gbworld.gb.co.uk/types/header/"
                                    xmlns:req="http://gbworld.gb.co.uk/types/core/request/">
            <ns5:securityheader>
                <head:authenticationtoken>1273F4FA-3AE7-4742-A0C6-626D006A445A</head:authenticationtoken>
                <head:authenticationtime>2014-02-14T13:05:11.000Z</head:authenticationtime>
                <head:sessionexpirytime>2014-02-14T13:35:20.449Z</head:sessionexpirytime>
            </ns5:securityheader>
            <ns5:transactionguid>8F9F9258-E772-45FC-B486-7F09FD3F067B</ns5:transactionguid>
            <ns5:profileresponse>
                <req:profileheader>
                    <req:profileguid>BCB96C1A-BC4C-4110-8A9E-A097B55380BB</req:profileguid>
                    <req:profilename>Matchcode AddressBase</req:profilename>
                    <req:transactionguid>8F9F9258-E772-45FC-B486-7F09FD3F067B</req:transactionguid>
                    <req:transactiontimestamp>2014-02-14T13:05:20.537Z</req:transactiontimestamp>
                    <req:profilestatus>SUCCESS</req:profilestatus>
                </req:profileheader>
                <req:profileresponsedetails>
                    <req:transactionguid>87F581B6-5EC4-4F5D-9335-245B95C33B05</req:transactionguid>
                    <req:componentname>AddressBase</req:componentname>
                    <req:componentstatus>SUCCESS</req:componentstatus>
                    <req:componentaction>VERIFY</req:componentaction>
                    <req:responsetype>CAPTURE</req:responsetype>
                    <req:notes>[]</req:notes>
                    <req:invoice>
                        <req:invoicelist>
                            <req:invoiceguid>8BBC5551-5093-4563-B03A-867E6482B7E6</req:invoiceguid>
                            <req:billinginformationguid>CCB1C022-BF7C-4C71-B445-710110FA0FC7
                            </req:billinginformationguid>
                            <req:billingpoints>1</req:billingpoints>
                            <req:creditsused>1</req:creditsused>
                            <req:datasetinvoices>
                                <req:datasetcode>ABL</req:datasetcode>
                                <req:billingpoints>1</req:billingpoints>
                                <req:recordsreturned>1</req:recordsreturned>
                                <req:datalicenceguid>CCB1C022-BF7C-4C71-B445-710110FA0FC7</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:matchScore>100</req:matchScore>
                        <req:matchLevel>PREMISE</req:matchLevel>
                        <req:outputStatus>VERIFIED</req:outputStatus>
                        <req:fieldStatus>33003000</req:fieldStatus>
                        <req:responseCount>1</req:responseCount>
                        <req:response>
                            <req:address>
                                <data:street>Threadneedle Street</data:street>
                                <data:town>LONDON</data:town>
                                <data:postCode>EC2R 8AH</data:postCode>
                                <data:buildingName>The Bank Of England</data:buildingName>
                                <data:stateRegion>London</data:stateRegion>
                                <data:countryCode>GBR</data:countryCode>
                                <data:dpsZipPlus>9ZG</data:dpsZipPlus>
                                <data:formattedAddress>The Bank Of England,Threadneedle Street,,LONDON,,EC2R 8AH</data:formattedAddress>
                                <data:additionalItems>
                                    <data:item>
                                        <data:key>DPA_DPS</data:key>
                                        <data:value>1A</data:value>
                                    </data:item>
                                    <data:item>
                                        <data:key>DATASOURCE</data:key>
                                        <data:value>ABL</data:value>
                                    </data:item>
                                </data:additionalItems>
                                <data:uprn>200000069805</data:uprn>
                                <data:lpi>
                                    <data:lpiLogicalStatus>1</data:lpiLogicalStatus>
                                    <data:paoText>THE BANK OF ENGLAND</data:paoText>
                                </data:lpi>
                                <data:blpu>
                                    <data:postcodeLocator>EC2R 8AH</data:postcodeLocator>
                                </data:blpu>
                                <data:streetDescriptor>
                                    <data:streetDescription>THREADNEEDLE STREET</data:streetDescription>
                                    <data:townName>LONDON</data:townName>
                                    <data:administrativeArea>CITY OF LONDON</data:administrativeArea>
                                </data:streetDescriptor>
                                <data:companyInformation/>
                                <data:rmUDPRN>27599055</data:rmUDPRN>
                            </req:address>
                        </req:response>
                    </req:captureresponse>
                </req:profileresponsedetails>
            </ns5:profileresponse>
        </ns5:executecaptureresponse>
    </soap-env:body>
</soap-env:envelope>

​
Error Information

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