Skip to content
Log inGet a demo

Global Powersearch Integration Guide


Global Powersearch, also known as single-line auto-complete, is a "google like" search method by which the user types into a single text field and is shown a list of potential matches which is rebuilt as they continue to type. This Service has been implemented as a REST Web Service in order to make a light Service achieving very quick response times.

Global Powersearch Searching

Global Powersearch provides two different types of searches: International Address Data and Geocode Data. Both services need two inputs: The COUNTRY_CODE (ISO Country Code) and the ADDRESS (or part of the address) to be found. The way this information must be provided to the service will be detailed below.

International Address Data

International Address Data will return a list of addresses matching to the information provided in the Request. The more accurate the information provided, the smaller the returned list.

Geocode Data

Geocode Data will return a positional information (latitude and longitude) for a particular Address. Unlike the International Address Data service, the provided address must be a unique existing address. Otherwise, the Geocode service won't return positional information

Output Formatting Options

Global Powersearch provides the possibility to format the returning address for the International Address Data search. The formatting will only apply when the Response has just one address rather than a list of addresses. In case of list of addresses, the formatting will be skipped. The formatting options can be found here:

Matchcode Formatting Options

The way these formatting options must be supplied to the service is detailed below in Section 4.2, in the scenario "Address Search (accurate address) & Formatting REQUEST"

Please note that formatting options should only be applied when submitting a full address (i.e. when the user selects a final address). The formatting request uses a separate search method and therefore if this search method is applied earlier (i.e. mid-search) then the result quality will be impacted and the User Experience will be sub-standard.

Using the Powersearch REST Service

The Global Powersearch REST WebService offers its two operations (International Address Data and Geocode Data) through the HTTP GET method so that all the data supplied to the Service must be in the URL as either part of this URL or as HTTP parameters.

The REST WebService offers the possibility to get the Response in two different formats: XML or JSON. In order to specify the preferred format in the Response the Accept Header Request Parameter must be supplied:

To get the Response in XML format: Accept: application/xml
To get the Response in JSon format: Accept: application/json

If the Accept Header Request Parameter is omitted, the XML format in the Response will be applied as the default format.

Authentication

As a REST Web Service, Global Powersearch uses Http Basic Authentication.

Briefly, the client must send its credentials (UserID and Password). This credentials must be the result of Base64 encoding of the next string: userID:password. This Base64 encoded string must be supplied as a Header Request Parameter.

Example:
The client wants to send the credentials Username: userexample and Password: passwordexample, so the string to send should be:
Authorization: Basic dXNlcmV4YW1wbGU6cGFzc3dvcmRleGFtcGxl

Authorization is the Header Request Parameter name, and Basic dXNlcmV4YW1wbGU6cGFzc3dvcmRleGFtcGxl the Header Request Parameter value where dXNlcmV4YW1wbGU6cGFzc3dvcmRleGFtcGxl is userexample:passwordexample encoded in Base64.

The above information must be sent within every request to the REST Web Service, so the client must be authenticated in every single request.

International Address Data

These are several examples of International Address Data Requests and Responses:

Scenario Notes
Address Search (not very accurate request) REQUEST Enter the ISO Country Code after .../powersearch/global/ and the address to be found in the Request Parameter address
https://idmp.gb.co.uk/idm-powersearch-rest/powersearch/global/GB?address=8 london road
Address Search (not very accurate request) RESPONSE As the Address introduced in the Request was not very accurate, the service return a list of matches.
(XML Response)                          
 
 
     
        1
        2015-06-04T11:23:47.775+01:00
        9223EF55-FF72-4E71-961F-5D112CDC6A1F
     
    8 London Road, Post Office Square, Tunbridge Wells, TN1 1BQ
    8 London Road, York Close, Biggleswade, SG18 8AG
    8 London Road, Woodmill Court, Ascot, SL5 8FF
    8 London Road, Lyme Green Park, Lyme Green, Macclesfield, SK11 0LD
    8 London Road, Old Mill Place, Romford, RM7 9QF
    8 London Road, Halstead, Sevenoaks, TN14 7DS
    8 London Road, Florence Farm Mobile Home Park, West Kingsdown, Sevenoaks, TN15 6BP
    8 London Road, Kaysland Park, West Kingsdown, Sevenoaks, TN15 6EN
    8 London Road, The Holt, Morden, SM4 5AP
    8 London Road, Grange Court, Wallington, SM6 7DT
(JSON Response)                         
 
{
   "sessionData":    {
      "sessionKey": "9223EF55-FF72-4E71-961F-5D112CDC6A1F",
      "sessionCommencement": 2015-06-04T11:23:47.775+01:00,
      "numberOfSessionTransactions": 1,                               
   },
   "matches":    [
      "8 London Road, Post Office Square, Tunbridge Wells, TN1 1BQ",
      "8 London Road, York Close, Biggleswade, SG18 8AG",
      "8 London Road, Woodmill Court, Ascot, SL5 8FF",
      "8 London Road, Lyme Green Park, Lyme Green, Macclesfield, SK11 0LD",
      "8 London Road, Old Mill Place, Romford, RM7 9QF",
      "8 London Road, Halstead, Sevenoaks, TN14 7DS",
      "8 London Road, Florence Farm Mobile Home Park, West Kingsdown, Sevenoaks, TN15 6BP",
      "8 London Road, Kaysland Park, West Kingsdown, Sevenoaks, TN15 6EN",
      "8 London Road, The Holt, Morden, SM4 5AP",
      "8 London Road, Grange Court, Wallington, SM6 7DT"
   ],
   "information": null
}
Scenario Notes
Address Search (accurate address) REQUEST Enter the ISO Country Code after .../powersearch/global/ and the address to be found in the Request Parameter address
https://idmp.gb.co.uk/idm-powersearch-rest/powersearch/global/GB?address=8 London Road, York Close, Biggleswade, SG18 8AG
Address Search (accurate address) RESPONSE As the Address introduced is very accurate, only one match is returned.
(XML Response)                          
 
 
     
        1
        2015-06-04T13:04:15.651+01:00
        7764B769-FF97-4FBD-BB0C-6F28F5798C6E
     
    8 London Road, York Close, Biggleswade, SG18 8AG, , ,
(JSON Response)                         
 
{
   "sessionData":    {
      "sessionKey": "7764B769-FF97-4FBD-BB0C-6F28F5798C6E",
      "sessionCommencement": 2015-06-04T13:04:15.651+01:00,
      "numberOfSessionTransactions": 1,                               
   },
   "matches": ["8 London Road, York Close, Biggleswade, SG18 8AG, , , "],
   "information": null
}
Scenario Notes
Address Search (accurate address) & Formatting REQUEST Enter the formatting option by using the Request Parameter format Parameter address
https://idmp.gb.co.uk/idm-powersearch-rest/powersearch/global/GB?address=8 London Road, York Close, Biggleswade, SG18 8AG&format=CA=1:TOWN
Address Search (accurate address) & Formatting RESPONSE According the formatting option introduced, the Town name must be in uppercase
(XML Response)                          
 
 
     
        1
        2015-06-04T13:04:15.651+01:00
        7764B769-FF97-4FBD-BB0C-6F28F5798C6E
     
    8 London Road, York Close, BIGGLESWADE, SG18 8AG, , ,
(JSON Response)                         
 
{
   "sessionData":    {
      "sessionKey": "7764B769-FF97-4FBD-BB0C-6F28F5798C6E",
      "sessionCommencement": 2015-06-04T13:04:15.651+01:00,
      "numberOfSessionTransactions": 1,                               
   },
   "matches": ["8 London Road, York Close, BIGGLESWADE, SG18 8AG, , , "],
   "information": null
}

Geocode Data

This is an example of Geocode Data Request and Response:

Scenario Notes
Geocode Search REQUEST In order to perform a Geocode Request, enter /geo after the ISO Country Code, and the address to be found in the Request Parameter address
https://idmp.gb.co.uk/idm-powersearch-rest/powersearch/global/GB/geo?address=8 London Road, York Close, Biggleswade, SG18 8AG
Geocode Search RESPONSE Geocode information for the given address in the Request
(XML Response)

8 London Road,York Close,Biggleswade,SG18 8AG,,, 52.086420 -0.258250
(JSON Response)                         
 
{                               
    "address": 
    {
       "freeFormat": "8 London Road,York Close,Biggleswade,SG18 8AG,,,",                                   
       "latitude": "52.086420",
       "longitude": "-0.258250"
    }
}

Session Management - IMPORTANT

International Address Searching provides a mechanism to ensure that the desired final address can be found within a fair time and number of transactions. Thus, all the requests needed to find an Address will be included in a Session. Sessions have a limit of either 50 transactions or 2 minutes.

If the client supplies a valid SessionKey, the request will be included in that Session. If the client supplies an invalid SessionKey or no SessionKey is provided (first request), the Powersearch Service will create a new Session where the current transaction will be included.

Note that an invalid SessionKey might be a wrong key or a key that represents a Session with more than 50 calls or more than 2 minutes of life.

Each new session key will result in a billing point and will therefore remove a credit for customers with Pre-pay transaction accounts. Please therefore ensure that Session keys are recycled throughout each instance of a customer searching for their address.

As it can be seen in the above examples, a SessionData element is returned in every Global Address Searching Response from the Service. This SessionData contains a SessionKey (to be used in next request), sessionCommencement (session commencement timestamp), and numberOfSessionsTransactions (number of Transactions already used in this Session)

Note that Session mechanism is to be used just in International Address Operation and not in Geocode operation.

This is an example of how to add a SessionKey to the request:

Scenario Notes
Including SessionKey in the International Address Search REQUEST Enter the parameter sessionkey with the SessionKey (got from the last Response to the Service).
https://idmp.gb.co.uk/idm-powersearch-rest/powersearch/global/GB?address=York&sessionkey=2432D120-1F36-4894-861D-E319C7636A22
International Address Search RESPONSE Address Search Response
(XML Response)                          
 
 
     
        5
        2015-06-04T15:16:12.548+01:00
        2432D120-1F36-4894-861D-E319C7636A22
     
    Yorkshire Bldg Soc, 355 Union Street, Aberdeen, AB11 6BT
    York House, York Place, Cullen, Buckie, AB56 4UW
    Yorker, Chequer Lane, Redbourn, St. Albans, AL3 7NH
    York Laurent Ltd, Unit 1, 12 Frederick Street, Birmingham, B1 3HE
    York Cafe, 16 York Road, Kings Heath, Birmingham, B14 7RZ
(JSON Response)                         
 
{
   "sessionData":    {
      "sessionKey": "2432D120-1F36-4894-861D-E319C7636A22",
      "sessionCommencement": 2015-06-04T15:16:14.348+01:00,
      "numberOfSessionTransactions": 7,                              
   },
   "matches":    [
      "Yorkshire Bldg Soc, 355 Union Street, Aberdeen, AB11 6BT",
      "York House, York Place, Cullen, Buckie, AB56 4UW",
      "Yorker, Chequer Lane, Redbourn, St. Albans, AL3 7NH",
      "York Laurent Ltd, Unit 1, 12 Frederick Street, Birmingham, B1 3HE",
      "York Cafe, 16 York Road, Kings Heath, Birmingham, B14 7RZ"
   ],
   "information": null
}

Get started for free today

  • No credit card required
  • Cancel any time
  • 24/5 support
Get started