Postcode Programming API  Street from HTTP/XML Web Service

Street Address Search functionality:

  1. Postcode is entered
  2. User presses search button
  3. Address filled in apart from House Name/Number
  4. User manually types in House Name/Number, unlike Full Address

To get a Street address from our HTTP/XML Web Service we do the following:

Step 1 Sign up for free 30 day trial

Simply use the "Sign Up for Trial" link at top right of this page to open a trial account.   We will then send you a data key, which is used to identify your account, when using the following service.

Step 2 Call fro Address Record

Call XMLService/XMLSearchForThoroughfareAddress.aspx to get address record

This call will retrieve the Thoroughfare/Street Address Data (Royal Mail Street PAF) for a given Postcode. The Street Address is a cut down version of the Full Address, basically it does not contain the Building name or number. Therefore the programmer should allow the user to enter the House Name/Number for the address. These licenses are cheaper than Full Postcode data.

Parameters

Parameter name Description
DataKey Datakey, which is available when account has been created, under the “DataKey” tab of the online account administrator page.
Username Only needed if for internal postcode address use
ip IP Address of client. This is optional. We monitor address queries and have had cases where client’s web sites have been used repeatly by one person. Specifying the IP address of each client allows to monitor and block such queries.
Postcode Postcode to search for
To retrieve residential property only. To do this simply append “[” to the end of the Postcode.
To retrieve commercial property only. To do this simply append “]” to the end of the Postcode.

 

Returns

 

Parameter name Description
data Data regarding the status of the account
errormessage Contains a message if error occurred when searching for Address by Postcode
accountadminpage URL for page to buy more Postcode Address licenses
credits_display_text Status of Postcode Address licenses. This shows the number of users/credit lookups available
found Equals “1” if data has been returned, thus process records below
record Address information.  See "Data returned" section below

 

Example

 

Call HTTP web service with your data key, which is e-mailed to you when you open an account.  The data key identifies your account and licenses.

 

        Web Service   
          
          www.simplylookupadmin.co.uk/XMLservice/XMLSearchForThoroughfareAddress.aspx?datakey=Your Data Key
&postcode=pe132ql&version=2

 

 

        Returns XML   
          
          <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
   <!DOCTYPE data [
   <!ELEMENT data(found,credits_ display_text, accountadminpage, errormessage,record)>

   <!ELEMENT found (#PCDATA)> 
   <!ELEMENT credits_display_text (#PCDATA)> 
   <!ELEMENT accountadminpage (#PCDATA)> 
   <!ELEMENT errormessage (#PCDATA)>
   <!ELEMENT record (line1,line2,line3,town,county,postcode, country, rawpostcode, mailsortcode, spare)>

      <!ELEMENT line1 (#PCDATA)> 
      <!ELEMENT line2 (#PCDATA)> 
      <!ELEMENT line3 (#PCDATA)> 
      <!ELEMENT town (#PCDATA)> 
      <!ELEMENT county (#PCDATA)> 
      <!ELEMENT postcode (#PCDATA)> 
      <!ELEMENT country (#PCDATA)> 
      <!ELEMENT rawpostcode (#PCDATA)> 
      <!ELEMENT mailsortcode (#PCDATA)>
      <!ELEMENT spare (#PCDATA)> 
      ]> 
               <found>1</found>

               <errormessage></errormessage>
   <credits_display_text>Evaluation expires 28 Jul 2010</credits_display_text>
   <accountadminpage>https://www.xxx...</accountadminpage>
   <errormessage></errormessage>

   <record>

                  <line1>Vicrotia Rd</line1>
      <line2></line2>
      <line3></line3>
      <town>Wisbech</town>
      <county>Cambridgeshire</county>
      <postcode>PE13 2QL</postcode>
      <country>England</country>
      <rawpostcode>PE132QL</rawpostcode>
      <mailsortcode>1033</mailsortcode>
      <spare></spare>
   </record>
</data>

 

 

If address returned then found = 1, else found = 0,error in errormessage

 

errormessage should be displayed if populated

If used by employee of company (classed as "Internal use")

It is a requirement of the royal mail that if postcode lookup software is used by an employee of a company, then the user must be uniquely identified so we can apply a user count.

Therefore the URL must contain a User ID:

www.simplylookupadmin.co.uk/XMLservice/XMLSearchForThoroughfareAddress.aspx?datakey=Your Data Key
&postcode=pe132ql&version=2&username=UserID

This will be the datakey beginning with "I"

Section 3.5 of the Terms and Conditions state: "The Customer, when using the Postcode Lookup service via Web Service, must make sure each user is identified by a unique Computer name, in each call to the Web Service if used internally”. In simple language this means that each user must be identified by a unique computer name, in username parameter, if used by a company employee.

Step 4 Testing

Final step is to test, to enable easy testing please use our special test postcodes.

Data Returned

This type of license returns: (see example below)

  • Street Name
  • Locality
  • Town
  • County
  • Postcode
  • Country "England","Wales","Northern Ireland","Isle of Man","Channel Islands","Scotland"
  • Mail sort Code