Simply Postcode Lookup                     Phone: 01945 464854 

   Log In       
Postcode Address Lookup Software
 

PAF Postcode Address Lookup via Web HTTP Service Request:


  Advantages

  • Platform/Language independent

  • Offers full access to all data we provide (Full/Thoroughfare/Distance)

  • Data always up to date

  • No Data Administration Cost for you

  • Can allow your customer to open an account, your get commission

      [More About being a Reseller]

     

 

   Click here for comprehensive help on HTTP/XML

   Please download examples here


   Tutorial Video : Programming interfaces & using example code

 

 

 Simply Postcode Lookup XML/ HTTP Web service offers a simple way to interact with our postcode address lookup service. This service provides up to date Royal mail address information.

The service is available across a simple HTTP protocol.  Each request is a standard HTTP GET request with the query string forming the request parameters, and returns the address Lookup information as XML.

Functions Available:

       Search for FULL PAF Address from Postcode

       Get for Thoroughfare Address from Postcode

       Get PostZon Data from Postcode (Longitude, Latitude and distance)

       Get Map/Nearest Service URL

       Your Nearest Store location with optional Google Map

       Get Route on Map URL

       Open an account and associate with reseller

       Account Status and Usage

       Get License Summary

 

   [What is Full, Thoroughfare and PostZon Data?]

  Search for FULL PAF Address from Postcode Search


  XMLService/XMLSearchForAddress.aspx

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

  Parameters:

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

version Set 1, this allows to change XML structure without effecting you software

postcode

Postcode to search for

Retrieving residential property only.  To do this simply append “[” to the end of the Postcode.

Retrieving commercial property only.  To do this simply append “]” to the end of the Postcode.

Address words, more info  (Internal use only)

All parameters must be in lower case

  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

line

Address line to display for selection, used in next part of search

  Example:

www.simplylookupadmin.co.uk/xmlservice/XMLSearchForAddress.aspx?datakey=xxxx

&postcode=pe132ql&version=1

  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> 

 

  XMLService/XMLGetAddressRecord.aspx

Gets the full address information given the ID

  Parameters:

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

version Set 2, this allows us to change XML structure without effecting you software

id

Record ID, to identify the Royal mail address record.  Royal mail PAF File

All parameters must be in lower case

  Returns:

Name

Description

data

Data regarding the status of the account

record

Full Address information

Element : “data”:

  Example:

www.simplylookupadmin.co.uk/xmlservice/XMLGetAddressRecord.aspx?datakey=xxxx

&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> 

 

  Fields of interest:

Name

Description

id Is only used for our internal use

deliverypointsuffix

This code can be added to the postcode to give a unique reference to each Delivery Point (letterbox) in a Postcode.  Although the UDPRN number is a better source of unique ID.

nohouseholds

Number of house holds at this postcode address

smallorg

Y = Small Organisation

pobox

PO Box number if PO Box address

rawpostcode

Postcode in its raw state.  7 chars long

mailsortcode

The Royal Mail offer discount if mail is sorted by this code

udprn

is a unique 8 digit code assigned to each addressable property (Delivery Point). 

unique

gives the unique portion of the address record, in the above example "44".   See Notes

spare

Contains "|" separated data  

Property No, Property Name, Street Name

See Notes

 

PHP examples can be found in "PHP Core Code" directory which show how to use this HTTP/XML Web Service.  [Download examples]

 

  Get Thoroughfare Address from Postcode Search


  XMLService/XMLSearchForThoroughfareAddress.aspx

This call will retrieve the Thoroughfare Address Data (Royal Mail Thoroughfare  PAF) for a given Postcode.   The Thoroughfare 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 the Full Postcode data.

    [What is Full, Thoroughfare and PostZon Data?]

  Parameters:

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

version Set 2, this allows us to change XML structure without effecting you software

postcode

Postcode to search for

All parameters must be in lower case

  Returns:

Name

Description

data

Data regarding the status of the account

record

Address fields.  Some fields may be blank.

  Example:

www.simplylookupadmin.co.uk/xmlservice/XMLSearchForThoroughfareAddress.aspx

?datakey=xxxx&postcode=pe132ql&username=administrator&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 (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)>  

]>

   <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> 

 

PHP examples can be found in "PHP Core Code" directory which show how to use this HTTP/XML Web Service.  [Download examples]

 

Get PostZon Data from Postcode Search


  XMLService/XMLSearchForPostZonData.aspx

This call will retrieve the PostZon Data for a given Postcode, OSRef, Longtitude/Latitude or by Town.   This PostZon data is collected from many different source by the Royal mail.   The most useful information is Distance from Home Postcode, Longitude and Latitude.

    [What is Full, Thoroughfare and PostZon Data?]

  Parameters:

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

postcode

Postcode to search for

To get the PostZon record by OSRef, simply set postcode to the OSRef.

 

To get the PostZon record by Longtitude/Latitude, (closest within 10Km) set postcode to the "Longtitude|Latitude" (separated by |).  The Postcode found will be returned in pz_postcode.

To get the Longitude and Latitude of a Town, simply provide the Town name + “,SPACE“ + County in the postcode field.  The Longitude and Latitude will then be returned.  It is suggested that the town list in displayed using a AJAX search box.

[Download town list]

 

version Set 1, this allows us to change XML structure without effecting you software
homepostcode To calculate the distance to another postcode, supply the HOME postcode here, this is optional

All parameters must be in lower case

  Returns:

Name

Description

data

Data regarding the status of the account

record

Address information

  Element : “record” PostZon Data:

Name

Description

pz_postcode Postcode in the PostZon record
pz_found

Found Yes or No

If no all data is null

pz_latitude_wgs84

Latitude.

This equals zero if not co-ordinates are available, see extra notes below

pz_longitude_wgs84

Longitude

pz_geodistancetohomepostcode

Distance from HOME postcode in Kilometres

-1 = Error

pz_introductiondate

Date introduced to file

pz_gridrefeast

Ordnance Survey 100m Easting and Northing measurements that refer to the distance east and north from a fixed point just South West of the Isles of Scilly. They indicate the mean centre point of a Postcode to 100m.

pz_gridrefnorth

Ordnance Survey 100m Easting and Northing measurements that refer to the distance east and north from a fixed point just South West of the Isles of Scilly. They indicate the mean centre point of a Postcode to 100m.

pz_county

Administrative and Local Health Authority codes used by the office of national statisics (2 Digits)

Description is after the ","

pz_district

Administrative and Local Health Authority codes used by the office of national statisics (2 Digits)

Description is after the ","

pz_ward

Local Authority Ward Codes in England and Wales are comprised of six characters - the first two digits represent the county, the next two alphabetic characters identify the Local Authority and the last two characters represent the electoral ward of the Postcode. Unitary Authorities in England, Wales and Scotland are four-character fields represented by the Local Authority and the Ward. In Northern Ireland, the 6 characters are made up of 95 plus a letter from A - Z followed by a space and the electoral Ward.

Description is after the ","

pz_usertype

0=Small User, 1=Large User

Description is after the ","

pz_gridstatus

Status of grid co-ordinates.  Latitude is aero if no grid co-ordinates are available, see extra notes below.

Description is after the ","

pz_country

064="England"
220="Wales"
179="Scotland"
152="Northern Ireland"
044="Channel Islands"
128="Isle of Man"

Description is after the ","

pz_wardstatus

Description is after the ","

pz_nhs_code

A three character code which identifies the Health Authority or board responsible for funding patient care within each Postcode.

Description is after the ","

pz_nhs_region

NHS Codes   

Description is after the "," 

pz_osreference

OS Reference. 

e.g PE132QL ="TF4630009100"

This is our national coordinate system for topographic mapping. It is used for Ordnance Survey mapping at all scales, and for many private topographic surveys.

The OSGB36 part of the name refers to the geodetic datum (system of latitude and longitude) used, and the National Grid part refers to the map projection and grid referencing convention for eastings and northings

pz_wardstatus

 

pz_mailsort

Is a unique 5-digit numeric codes used internally by Royal Mail to route mailbags.  They are also used by external customers with Mailsort contracts, which is why they are present in the data.

 

Information about Grid East and Grid North

The standard grid east and grid north fields are five character codes which give a value in tens of metres.  Thus the maximum value of 99999 corresponds to a distance of just under 1000 km or 625 miles.  Given the grid origin just south and west of the Isles of Scilly, this is sufficient for the eastings (maximum is 70352) but not for the northings.  The northernmost northings therefore have an initial letter and not a digit, and this corresponds to a numeric value as follows:

Y or Z  10

T or U  11

O or P  12

The Northern Irish grid does not have the same origin as the one used for the rest of the United Kingdom.  Consequently the values as present on Postzon overlap with the other areas of the UK.  Belfast, for example, has the same coordinates as parts of Cheshire and Merseyside.  An approximate conversion of Northern Irish grid references to the same origin as the rest of the UK is obtained by adding 13000 to the northing and subtracting 17000 from the easting of the NI references.  This should not be regarded as an exact conversion.  

Grid information is not available for

  • Postcodes with no coordinates are PO box’s, i.e. they have no physical location
  • Isle of Man, Channel Islands

  Example:

www.simplylookupadmin.co.uk/xmlservice/XMLSearchForPostZonData.aspx?datakey=xxxx

&postcode=pe132ql&username=administrator&version=1

  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(pz_introductiondate, pz_gridrefeast, pz_gridrefnorth,

      pz_county, pz_district, pz_ward, pz_usertype, pz_gridstatus, pz_country,

      pz_wardstatus, pz_nhs_code, pz_nhs_region, pz_latitude_wgs84,

      pz_longitude_wgs84, pz_osreference, pz_geodistancetohomepostcode)>


      <!ELEMENT pz_introductiondate (#PCDATA)> 

      <!ELEMENT pz_gridrefeast (#PCDATA)> 

      <!ELEMENT pz_gridrefnorth (#PCDATA)> 

      <!ELEMENT pz_county (#PCDATA)> 

      <!ELEMENT pz_district (#PCDATA)> 

      <!ELEMENT pz_ward (#PCDATA)> 

      <!ELEMENT pz_usertype (#PCDATA)> 

      <!ELEMENT pz_gridstatus (#PCDATA)> 

      <!ELEMENT pz_country (#PCDATA)> 

      <!ELEMENT pz_wardstatus (#PCDATA)> 

      <!ELEMENT pz_nhs_code (#PCDATA)> 

      <!ELEMENT pz_nhs_region (#PCDATA)> 

      <!ELEMENT pz_latitude_wgs84 (#PCDATA)> 

      <!ELEMENT pz_longitude_wgs84 (#PCDATA)> 

      <!ELEMENT pz_osreference (#PCDATA)> 

      <!ELEMENT pz_geodistancetohomepostcode (#PCDATA)>]>

      <!ELEMENT pz_postcode (#PCDATA)>]>

]>

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

   <errormessage></errormessage>

   <record>
      <pz_introductiondate>19981231</pz_introductiondate>
      <pz_gridrefeast>31830</pz_gridrefeast>
      <pz_gridrefnorth>17610</pz_gridrefnorth>
      <pz_county>00,Description</pz_county>
      <pz_district>PT,Description</pz_district>
      <pz_ward>NK,Description</pz_ward>
      <pz_usertype>0,Small User</pz_usertype>
      <pz_gridstatus>2,Description</pz_gridstatus>
      <pz_country>220,Description</pz_country>
      <pz_wardstatus>1,Description</pz_wardstatus>
      <pz_nhs_code>Q99,Hospital</pz_nhs_code>
      <pz_nhs_region>W00,East Anglia</pz_nhs_region>
      <pz_latitude_wgs84>52.660218</pz_latitude_wgs84>
      <pz_longitude_wgs84>0.162724</pz_longitude_wgs84>
      <pz_osreference>TF4630009100</pz_osreference>
      <pz_geodistancetohomepostcode>3</pz_geodistancetohomepostcode>

      <pz_postcode >PE132QL</pz_postcode >
   </record>
</data>

 

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

 

PHP examples can be found in "PHP Core Code" directory which show how to use this HTTP/XML Web Service.  [Download examples]

 

  Get URL for Map/Nearest Service from Postcode


Simply make a call to the following functions get the URL or display a map based on the Postcode, at one of three zoom levels.

  GetUrlforPrefuredMap.aspx?postcode=PE132ql&zoomlevel=Street

 

Zoom level can be Street, District or Area.

A directory of the nearest services can also be obtained using:

  GetUrlforPrefuredMap.aspx?postcode=PE132ql&zoomlevel=SERVICE:Hospital

This will result in a list of "hospitals" nearest to PE132QL.

  GetUrlforPrefuredMap.aspx?postcode=Wisbech&zoomlevel=SERVICE:Hospital

This will result in a list of "hospitals" nearest to "Wisbech".


  Display Route on Map


Simply make a call to the following functions get the URL or display a Map with a best route superimposed.

  GetUrlforPrefuredMap.aspx?postcode=PE132QL&zoomlevel=ROUTE:PE132XQ

where PE132QL is the start point

and PE132XQ is a list of delivery address (comma separated)

 

  Example code:

So calling GetUrlforPrefuredMap("PE132QL","ROUTE:PE132XQ,DG14BX") will display map of route

 

Open an Account and associate with reseller


Create an account and assign you as the reseller.  It can link your own Reseller account to a customers so you get commission on ALL purchases.  Please apply to be a reseller at http://www.simply-postcode-lookup.com/Reseller.htm

 

The call one of:

Internal Use

'For Internal Use (All Desktop Software and Web Software used internally within a company)

  http://www.simplylookupadmin.co.uk/A2CustomerAccount/

         WebAccountCreateFromReseller.aspx ?r=I&id=4

 

Where 4 is your reseller ID

Web Use    

'or For Web Use (All Web Software used by customer)

  http://www.simplylookupadmin.co.uk/A2CustomerAccount/

         WebAccountCreateFromReseller.aspx?r=W&id=4

Both

http://www.simplylookupadmin.co.uk/A2CustomerAccount/

         WebAccountCreateFromReseller.aspx?r=&id=4

  Get License Information


This call allows the Reseller to check a customer Internet based license, to make sure the customer is attached to them as Reseller, and check demo status.  

It should be called after setting the Datakey, with the type of search you are interested in testing.  F=Full Address, T=Throughfare Address, Z=PostZon.  Username should be specified for internal use.

  http://www.simplylookupadmin.co.uk/A2CustomerAccount/

         XMLAccountInfo.aspx?datakey=xxxxx&searchtype=F&username=ME

 

Returns:

Name

Description

errormessage

Description of error if fails

validlicense

“yes” if a license exist for this user for SearchType, else "no"

licensestatustext

Text describing the license and its status

ondemo

yes” if on demo, else "no"

demoarea

Postcode area of demo

demoexpire

Date demo will expire if on demo 

REID

Reseller ID

An account can have a valid license and still be on evaluation.  Thus allowing a user to test another service, as well as having an actual license.   But if a valid license is found, for SearchType, then “ondemo” will be “no”.

 

Account Status and Postcode Lookup Usage


You may want to provide a screen to show the Simply Postcode account status, in your software, or for you customer.  We provide this functionality on our web server, this can be access from the link on the e-mail first sent to you when opening an account or from the [Licenses Status and Usage] link on the first page of your on line account.

It is advisable to bookmark this page, for easy access.

It shows you:

  • Graph of Postcode Lookup usage
  • PAF licenses, with Postcode Lookup credit count or number of users
  • Date predicted to expire, if credit based license
  • Simple links allow you to top up your account or add extra users *
  • Shows if you have an outstanding invoice with us *

 

* = not if a resellers customer, on direct invoice mode

 

Other Interfaces Available:


.Net Integration for VB.NET, ASP.NET, C# and j#
HTTP/XML Web Service
COM object for Bespoke Software in VB, C++, Delphi, MS Access and many other main stream languages

Web Site Lookup Pop-up

Postcode Lookup Software © ComTek Accounts 2005

Internet Postcode Address Lookup Software

 

PAF Postcode Address Lookup Software for Web Sites

PAF Postcode Address Lookup Software using .NET and SOAP Services

COM Object for PAF Postcode Address Lookup Software

Nearest Store Location functionality

PAF Postcode Address Lookup Software Desktop Application Manual

PAF Postcode Address Lookup using HTTP to request XML data

PAF Postcode Address Lookup Software Troubleshooting

PAF Postcode Address Lookup Software WEB Troubleshooting

Terms and Conditions

Home Page

 
  • Competitive pricing
  • No set-up Charges
  • Over 99.9% Availability
  • Always up to date
  • Free Trial software
  • Free Technical Support
  • No hidden extra charges
  • Instant Access
  • Programming Examples
  • Local or Internet Data
 
Simply Postcode Lookup Software Award