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

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

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

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

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

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: