Developers

AddressVal ™

1. REST
2. SOAP

Important note.

AddressVal™ is available on both main and backup servers at our primary and secondary data centres.

In general:

  • Call the service at the primary data centre at www.unifiedservices.co.uk
  • In the unlikely event of a failure, call the service at the secondary data centre at www.unifiedsoftware.co.uk

1 AddressVal™ - REST


AddressVal™ functionality:

  • Given a partial address comprising of premise number/name and postcode, AddressVal™ will return one or more address matches from the Royal Mail PAF database.
  • If AddressVal™ is able to find an exact match on the database, a single result is returned to the user, containing full address details.
  • If an exact match cannot be found, AddressVal™ will return a number of possible matches, from which the user may make a selection. Each returned match will comprise of the full UK postal address.

Follow these three steps:-

  • 1. Attempt to access the service on unifiedservices.co.uk
  • 2. Check the http response code
  • 3. If this is < 200 or > 399, access the backup service on unifiedsoftware.co.uk

URI for AddressVal™

  • GET http://www.unifiedservices.co.uk/services/addrval/address/userid/<userid>/pin/<pin>/premise/<premise>/
    postcode/<postcode>/<format>/
  • If http response code is < 200 or > 399 then call:-
  • GET http://www.unifiedsoftware.co.uk/services/addrval/address/userid/<userid>/pin/<pin>/premise/<premise>/
    postcode/<postcode>/<format>/

where:

  • <userid> and <pin> are your user ID and 5 digit PIN obtained upon request from: sales@unifiedsoftware.co.uk
  • <premise> is the property name or number.
  • <postcode> is the property postcode.
  • <format> specifies the format of the returned data. Valid formats are csv, xml and json.
  • Please note that if you wish to use a parameter which includes a special character such as a space, this will need to be ‘escaped’, i.e. replaced with a code which is valid within a URI
  • For example, if premise is ‘Rose Cottage’, this should be replaced by ‘Rose%20Cottage’ in the URI:
    .../premise/Rose%20Cottage/postcode/ ...
  • If the premise name or number is not known, insert the word ‘all’ to receive all matches for a given postcode. Do not leave the premise field blank.

Results

If the postcode is valid:-

  • One or more possible matches is returned, each comprising of the full postal address.
  • CSV return strings are comma “,” and pipe “|” delimited. Fields within an address are separated by commas and whole addresses are separated by pipe characters. It is common for some of the fields to be empty.
  • JSON and XML results are prefixed with the term "VALID".

Example Valid Results

Sample valid response in xml format :-

<addresses>

<address>

  • <result>VALID</result>
  • <premise>31</premise>
  • <dependentstreet></dependentstreet>
  • <street>New Bridge Street West</street>
  • <doubledependentlocality></doubledependentlocality>
  • <dependentlocality></dependentlocality>
  • <posttown>NEWCASTLE UPON TYNE</posttown>
  • <county></county>
  • <postcode>NE1 8AQ</postcode>

</address>

<address>

  • <result>VALID</result>
  • <premise>Nationwide Bldg Soc 9</premise>
  • <dependentstreet></dependentstreet>
  • <street>New Bridge Street West</street>
  • <doubledependentlocality></doubledependentlocality>
  • <dependentlocality></dependentlocality>
  • <posttown>NEWCASTLE UPON TYNE</posttown>
  • <county></county>
  • <postcode>NE1 8AQ</postcode>

</address>

</addresses>


Sample valid response in json format :-

  • {"addresses":[
  • {"address":{"result":"VALID",
  • "premise":"31",
  • "dependentstreet":"",
  • "street":"New Bridge Street West",
  • "doubledependentlocality":"",
  • "dependentlocality":"",
  • "posttown":"NEWCASTLE UPON TYNE",
  • "county":""
  • "postcode":"NE1 8AQ"}},
  • {"address":{"result":"VALID",
  • "premise":"Browell Smith & Co Perl Assurance House 7"
  • "premise":"",
  • "street":"New Bridge Street West",
  • "doubledependentlocality":"",
  • "dependentlocality":"",
  • "posttown":"NEWCASTLE UPON TYNE",
  • "county":"",
  • "postcode":"NE1 8AQ"}}
  • ]}

Sample valid response in csv format :-

  • 31,,New Bridge Street West,,,NEWCASTLE UPON TYNE,,NE1 8AQ| Browell Smith & Co Pearl Assurance House 7,,New Bridge Street West,,,NEWCASTLE UPON TYNE,,NE1 8AQ|

If premise and postcode are not valid or if an error occurs:-

  • Return field - contains an error message

Error messages :-

Error Messages

ERROR - UserID Expired - Trial user ID has expired.

ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.

ERROR - Insufficient address input - The postcode is not complete.

ERROR - No matching address found - The postcode is not valid.

ERROR - Too many matching addresses - Too many matching addresses for given input.


<< Back to Top >>


2 AddressVal™ - SOAP


AddressVal™ functionality:

  • Given a partial address comprising of premise number/name and postcode, AddressVal™ will return one or more address matches from the Royal Mail PAF database.
  • If AddressVal™ is able to find an exact match on the database, a single result is returned to the user, containing full address details.
  • If an exact match cannot be found, AddressVal™ will return a number of possible matches, from which the user may make a selection. Each returned match will comprise of the full UK postal address.

Accessing AddressVal™ via SOAP

The simplest way to access the SOAP service is via its WSDL (Web Service Definition Language) file. This can be used by many SOAP toolkits to generate the client code necessary to consume the web service.

Parameter Format for AddressVal

ReturnMessage = addresscheck(QueryString)

where

QueryString is a " | " delimited string of the format - "userid|PIN|premise_name_or_number|postcode"

ReturnMessage is string delimited by coma and pipe characters or an error message as shown below.

If ReturnMessage contains valid address/addresses :-

  • Fields within an address are separated by commas and whole addresses are separated by pipe characters. It is common for some of the fields to be empty.
  • A single address is comprised of the following fields:
    premise, dependent_street, street, double_dependent_locality, dependent_locality, post_town, county (currently empty, may be populated in a future release), postcode

Example Valid Results

A typical example of an exact match might look like:-

  • 23,,Acacia Gardens,,Gilesgate,Durham,,DH1 1AB

A example of a ‘fuzzy’ match might look like:-

  • 23,,Acacia Gardens,,Gilesgate,Durham,,DH1 1AB|23,,Acacia Gardens,,Solihull,Birmingham,,B3 1AB|23,, Acacia Avenue,,,Plymouth,,PY1 1AB|etc

If premise and postcode are not valid or if an error occurs:-

  • An error message is returned

Error Message

ReturnMessage meanings

ERROR - UserID Expired - Trial user ID has expired.

ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.

ERROR - Insufficient address input - The postcode is not complete.

ERROR - No matching address found - The postcode is not valid.

ERROR - Too many matching addresses - Too many matching addresses for given input.


<< Back to Top >>