Programming API:
Demo video
Getting Started
Compare API's
API Interfaces
SOAP Web Service
HTTP/XML Web Service
Features and Examples
Getting Full Address
Advanced/Word Search
Getting Street Address
Get Long/Lat and Dist
Usage Summary
Reseller Functions
JSON Web Service
COM Object
.NET Assembly
Example Downloads
Request a Quote and Brochure
Save us:
Bookmark page
Send to a Friend
Print this page
Follow us:
Features:
Competitive pricing
No set-up Charges
Over 99.99% Availability
Free Trial Software
Free Technical Support
Try before you buy
Local or Internet Data
Reseller Opportunities
    Postcode finder using data supplied by royal mail
Updated Daily

Postcode Programming API  Get Full Address from HTTP/XML Web Service:

Full Address Search functionality:

  • Enter postcode
  • Presents a list of addresses at postcode
  • Address is selected.
  • Full address returned

To get a full 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 XMLService/XMLSearchForAddress.aspx for list of address at Postcode

Returns a series of lines, from which the user can select full royal mail address information (Royal mail PAF Database). XMLGetAddressRecord.aspx (Step 2) is then called with the selected address id, to get full address information.

Parameters

Parameter name Description
DataKey Datakey, which is available when account has been created, under the “DataKey” tab of the online account administrator page.
version Set 1, this allows to change XML structure without effecting you software
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

Name Description
data Data regarding the status of the account
addressdata Address information

Element : “data”:

Name Description
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
addressdata Contains address

Element : “addressdata”:

Name Description
recordcount Count of records returned
records A series of records, for selection by user.
Each has a unique Identifier

Element : “record”:

Name Description
id ID of address line to later call for compete address (step 3)
line Address line to display for selection, used in next part of search

Example HTTP call:

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 in our system.

www.simplylookupadmin.co.uk/XMLservice/XMLSearchForAddress.aspx?datakey=Your Data Key&postcode=pe132ql

   Returns

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
   <!DOCTYPE data [
   <!ELEMENT data (found, credits_display_text, accountadminpage, errormessage, addressdata)>


   <!ELEMENT found (#PCDATA)>
   <!ELEMENT credits_display_text (#PCDATA)>
   <!ELEMENT accountadminpage (#PCDATA)>
   <!ELEMENT errormessage (#PCDATA)>


   <!ELEMENT addressdata (maxresults,recordcount,records*)>
      <!ELEMENT maxresults (#PCDATA)>
      <!ELEMENT recordcount(#PCDATA)>
      <!ELEMENT records (record)>

      <!ELEMENT record (id, line)>
         <!ELEMENT id (#PCDATA)>
         <!ELEMENT line (#PCDATA)>
]>

<data>
   <found>1</found>
   <errormessage></errormessage>
   <accountadminpage>http://xxx...xxx</accountadminpage>
   <credits_display_text>1/1 users</credits_display_text>

   <addressdata>
      <maxresults>0</maxresults>
      <recordcount>2</recordcount>

      <records>
         <record>
            <id>11570840_0e</id>
            <line>44 Victoria Road Wisbech</line>
         </record>
         <record>
            <id>11570841_0e</id>
            <line>48 Victoria Road Wisbech</line>
         </record>
      </records>

   </addressdata>
</data>

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

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/XMLSearchForAddress.aspx?datakey=Your Data Key&postcode=pe132ql&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 3 Call XMLService/XMLGetAddressRecord.aspx Get Address Record

Gets the full address information given the ID.  Now call to get the full address record information for the address line selected by user.

Parameters

Parameter name Description
DataKey Datakey, which is available when account has been created, under the “DataKey” tab of the online account administrator page.
version Set 2, this allows us to change XML structure without effecting you software
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.
id Record ID, to identify the Royal mail address record. Royal mail PAF File

Returns

Parameter name Description
data Data regarding the status of the account.  Documented in Step 2 above.
record Full Address information

Element : “data”:

See section below on data returned

Example:

Call HTTP web service with your data key.

www.simplylookupadmin.co.uk/XMLservice/XMLGetAddressRecord.aspx?datakey=Your Data Key&id=11570840_0E&version=2

   Returns

<?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 (id, organisation, line1, line2, line3, town, county, postcode, country,
               rawpostcode, deliverypointsuffix,nohouseholds, smallorg, pobox, mailsortcode,
               udprn,unique, spare )>
      <!ELEMENT id (#PCDATA)>
      <!ELEMENT organisation (#PCDATA)>
      <!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 deliverypointsuffix (#PCDATA)>
      <!ELEMENT nohouseholds (#PCDATA)>
      <!ELEMENT smallorg (#PCDATA)>
      <!ELEMENT pobox (#PCDATA)>
      <!ELEMENT mailsortcode (#PCDATA)>]>
      <!ELEMENT udprn (#PCDATA)>
      <!ELEMENT unique (#PCDATA)>
      <!ELEMENT spare (#PCDATA)>
   <data>

   <found>1</found>
   <credits_display_text>Evaluation expires 28 Jul 2010</credits_display_text>
   <accountadminpage>https:/...</accountadminpage>
   <errormessage></errormessage>

   <record>
<id>11570840_0E</id>
      <organisation>Comtek</organisation>
      <line1>44 Victoria Road</line1>
      <line2></line2>
      <line3></line3>
      <town>Wisbech</town>
      <county>Cambridgeshire</county>
      <postcode>PE13 2QL</postcode>
      <country>England</country>
      <deliverypointsuffix>2N</deliverypointsuffix>
      <nohouseholds>1</nohouseholds>
      <smallorg>N</smallorg>
      <pobox></pobox>
      <rawpostcode>PE132QL</rawpostcode>
      <mailsortcode>18962</mailsortcode>
      <udprn>19147292</udprn>
      <unique>44</unique>
      <spare>44||Victoria Road|||</spare>
   </record>
</data>

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

Step 4 Get Address record based on record select

When the users selects a record then simply get it using the sames call as in step 3 of the "Full Address" search


Data Returned:

This type of license returns: (see example below)

  • id ●
  • organisation (Company name)
  • line1
  • line2
  • line3
  • town
  • county
  • postcode
  • country. "England","Wales","Northern Ireland","Isle of Man","Channel Islands","Scotland"
  • mailsortcode ●
  • unique ●
  • deliverypointsuffix ●
  • nohouseholds ●
  • udprn ●   (Royal mail unique id for each address)
  • rawpostcode ● (formated postcode 7 chars long)
  • Spare ●

● see Additional Data Returned by Postcode Finder API for more information