Simply Postcode Lookup Software

JSON Web Service Features:

---

The JSON Web Service has the following features:

• Platform/Language independent
• Offers full access to all data we provide (Full/Thoroughfare/Geographic Longitude and Latitude)
• Data always up to date
• No Data Administration Cost for you
• Advanced Word Search on Address Data

Get Full Address from JSON Web Service:

---

To get a full address from our JSON Web Service we do the following:

Step 1 Call JSONService/JSONSearchForAddress.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). JSONGetAddressRecord.aspx (Step 2) is then called with the selected address id, to get full address information.

Example:

Call JSON 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 within our system.

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

Returns

{    "found":"1",    "credits_display_text":"Evaluation till 3 Apr 2011",    "accountadminpage":"https://www.simplylookupadmin.co.uk/WebAccountLogin.aspx?                               doid=1&coid=3333305462&Pay=yes",    "errormessage":"",    "maxresults":"0",    "recordcount":"7",    "records":[        {"l":"Victoria Lodge 18 Victoria Road Wisbech", "id":"31597197_2535693S_F"},        {"l":"1 Victoria Road Wisbech", "id":"11570811_0S_F"},        {"l":"2 Victoria Road Wisbech", "id":"34692202_0S_F"},        {"l":"3 Victoria Road Wisbech", "id":"11570828_0S_F"},        {"l":"5 Victoria Road Wisbech", "id":"11570842_0S_F"},        {"l":"46 Victoria Road Wisbech", "id":"34692229_0S_F"},        {"l":"48 Victoria Road Wisbech", "id":"11570841_0S_F"}    ] }

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

<errormessage> should be displayed if populated

  Please note: 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, if used by a company employee

Step 2 Call JSONService/JSONGetAddressRecord.aspx Get Address Record

Gets the full address information given the Address ID listed in previous step.  Now call to get the full address record information for the address line selected by user.

Example:

Call JSON web service with your data key.

www.simplylookupadmin.co.uk/JSONservice/JSONGetAddressRecord.aspx?datakey=Your Data Key&id=11570838_0S_F

Returns

{    "found":"1",    "credits_display_text":"Evaluation expires 3 Apr 2011",    "accountadminpage":"https://www.simplylookupadmin.co.uk/WebAccountLogin.aspx?                               doid=1&coid=3333305462&Pay=yes",    "errormessage":"",    "id":"31567757_2957290S_F",    "organisation":"Tesco",    "line1":"Barford Road",    "line2":"",    "line3":"",    "town":"St. Neots",    "county":"Cambridgeshire",    "postcode":"PE19 2SA",    "country":"England",    "rawpostcode":"PE192SA",    "deliverypointsuffix":"1N",    "nohouseholds":"1",    "smallorg":"Y",    "pobox":"",    "mailsortcode":"66140",    "udprn":"50394326" }

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/JSONservice/JSONSearchForAddress.aspx?datakey=Your Data Key
&postcode=pe132ql&username=UserID

and

www.simplylookupadmin.co.uk/JSONservice/JSONGetAddressRecord.aspx?datakey=Your Data Key&id=11570838_0S_F&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.

  Full Online API Reference Manual : JSON Web Service

Get Full Address using Advanced/Word Search:

---

The JSON Web Service also supports our advanced/word search when used for Internal Use. This allows the user to enter partial address words to find the full address in the Royal Mail Postcode Address file.

The principle, of searching, is very similar to the Full Address Postcode Finder described in section above.  Except it has more parameters.

Extra Parameters for Advanced Search:

To perform an advanced search, two of the following fields should be filled in with criteria

  One or more of the following:

Parameter name	Description
organistaion	Enter most distinctive word of Organisation name. Start of words can be entered by using * For example “StartOfWord*”
buildingornumber	Enter most distinctive word of Building Name or number. Start of words can be entered by using * For example “StartOfWord*”
street	Enter most distinctive word of Street/Road or Avenue Name. Start of words can be entered by using * For example “StartOfWord*”

  And one of the following from a selection list:

Parameter name	Description
townorvillage	Town or village name selected from a list
county	County name selected from a list
postarea	Start of Postcode (Outer Postcode) selected from a list

The XML list of TownOrVillage, County, and Postcode Outer can be downloaded from URL:

  http://www.simplylookupadmin.co.uk/XMLService/GetLookups.aspx?datatype=1

This list should be written to a local store, and displayed for user to select from.

  Tutorial Video : Show Advanced Search in Action

  Note: Only the first 100 lines of advanced search results are returned. In which case the criteria should be refined.

  This type of search is only available to “Internal use” type of license

Example

www.simplylookupadmin.co.uk/JSONservice/JSONSearchForAddress.aspx?datakey=Your Data Key &organistaion=Tesco&buildingornumber=&street=&townorvillage=&county=Cambridgeshire&pobox=&postarea=

Returns

{    "found":"1",    "credits_display_text":"Evaluation till 3 Apr 2011",    "accountadminpage":"https://www.simplylookupadmin.co.uk/WebAccountLogin.aspx?                   doid=1&coid=3333305462&Pay=yes",    "errormessage":"",    "maxresults":"99",    "recordcount":"2",    "records":[       {"l":"Tesco Barford Road St. Neots Cambridgeshire PE19 2SA England", "id":"31567757_2957290S_F"},       {"l":"Tesco 2 Cross Way Peterborough Cambridgeshire PE4 6NA England", "id":"29530895_1945471S_F"}    ] }

<errormessage> should be displayed if populated

If <recordcount>0</recordcount> then nothing found

If <recordcount>100</recordcount> then you need to refine the search query since this query will return a maximum of 100 lines. In which case you should add a line to the list saying “Gone over limit of 100 lines, please refine search....”. To test this set to organisation=”tesco” and townorvillage=”London”

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/JSONservice/JSONSearchForAddress.aspx?datakey=Your Data Key &organistaion=Tesco&buildingornumber=&street=&townorvillage=&county=Cambridgeshire&pobox=&postarea= &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.

Get Thoroughfare/Street from JSON Web Service:

---

To get a Thoroughfare/Street address from our JSON Web Service we do the following:

Call JSONService/JSONSearchForThoroughfareAddress.aspx to get address record

This call will retrieve the Thoroughfare Address Data, from the Royal Mail Thoroughfare PAF database, 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 than Full Postcode data.

Example:

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

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

Returns

{    "found":"1",    "credits_display_text":"Evaluation expires 3 Apr 2011",    "accountadminpage":"https://www.simplylookupadmin.co.uk/WebAccountLogin.aspx?                                              doid=1&coid=3333305462&Pay=yes",    "errormessage":"",    "line1":"Victoria Road",    "line2":"",    "line3":"",    "town":"Wisbech",    "county":"Cambridgeshire",    "postcode":"PE13 2QL",    "country":"England",    "rawpostcode":"PE132QL",    "mailsortcode":"66144" }

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/JSONservice/JSONSearchForPostZonData.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.

  Full Online API Reference Manual : JSON Web Service