Get Full Address from JSON/JSONP Web Service
Our JSON Web service allows the programmer to quickly and easily implement Postcode Address Lookup Software with own Web Page or App with Full Address search.
To get a full address from our JSON/JSONP Web Service we do the following:
Step 1 Sign up for 30 day free 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 for list of address at Postcode
Step 2 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.
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 |
| version | Set 1, this allows to change JSON structure without effecting you software |
| 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 find 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. |
| jsoncallback | JSONP callback function name |
| cross | cross=true will allow cross orgin calls to overcome a CORS Error
|
Returns
| 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 |
| recordcount | Count of records returned |
| records | A series of records, for selection by user. Each has a unique Identifier |
Element : “records”:
| Name | Description |
|---|---|
| id | ID of address line to later call for compete address (step 3) |
| l | Address line to display for selection, used in next part of search |
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.
Web Service
www.simplylookupadmin.co.uk/JSONservice/JSONSearchForAddress.aspx?datakey=Your
Data Key
&postcode=pe132ql
Returns json
{
"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 3 Get Address Record
Call
JSONService/JSONGetAddressRecordV2.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.
A second version of this call, JSONGetAddressRecordV2.aspx, is provided which returns the ‘unique’ and ‘spare’ field in addition to the normal address fields. See Data Returned below.
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 |
| jsoncallback | JSONP callback function name |
| cross | cross=true will allow cross orgin calls to overcome a CORS Error
|
Returns
| Parameter name | Description |
|---|---|
| data | Data regarding the status of the account. Documented in Step 2 above. |
| record | Full Address information, see "Data returned" section below |
Example
Call JSON web service with your data key.
Web Service
www.simplylookupadmin.co.uk/JSONservice/JSONGetAddressRecordV2.aspx?datakey=Your
Data Key&id=11570838_0S_F
Returns json
{
"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":"23 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",
"spare":"23||Barford Road||||||||||",
"unique":"23",
"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:
Web Service
www.simplylookupadmin.co.uk/JSONservice/JSONSearchForAddress.aspx?datakey=Your
Data Key
&postcode=pe132ql&username=UserID
or
www.simplylookupadmin.co.uk/JSONservice/JSONGetAddressRecordV2.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.
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)
- id ●
- organisation (Company Name)
- line1
- line2
- line3
- town
- county
- postcode
- country "England","Wales","Northern Ireland","Isle of Man","Channel Islands","Scotland"
- mailsortcode
- rawpostcode ●
- unique ● (JSONGetAddressRecordV2.aspx)
- spare ● (JSONGetAddressRecordV2.aspx)
- deliverypointsuffix ●
- nohouseholds ●
- udprn ● (Royal mail unique id for each address)
● see Additional Data Returned by Postcode Finder API for more information