Postcode Finder Address Open API
Our Open API Address Finder JSON Web Service provides Postcode, Postcode + Part of address or words "search as you type" using JSON Web service, which can be used by almost any programming language on any platform.
How to add "Search as your type" Address Lookup to my Application using an API?
Our Open API Address Finder JSON Web Service provides Postcode, Postcode + Part of address or words "search as you type" using JSON Web service.
Getting Started
What makes us different:
Summary of Search Process
- User types in Postcode, Postcode + Part of address or words (search as you type)
- Then presses Find button, or for Search as you Type, you implement a timer based on key up event to fire query 300ms after the last key up event
getaddresslist()is called to get a list to present to the user- User selects from the list. The Line ID is then used to get selected Full Address details + GeoLocation from
getselectedaddress() - The response is processed and displayed to the user.
How to Implement "Search as you Type"
The following can be pasted into Chat GPT to write code for your specific languages/platforms. We have an example of this code for a c# desktop app View Postcode Address Finder Example on Git Hub
Chat GPT Question used to create such an Example
First in c# .Net App we created a form with:
Note also we are calling full_v3/getaddresslist with &options=B which will Add
and around the results matching text. You may not want this.
Simply change "In c#, .net 4.8 Windows app, " to what ever ... and ask chat GPT...
Generate Example in Chat GPT or Similar
In c#, .net 4.8 Windows app, I need to add to a text box "textBoxFind" to perform a search, which
calls an API given at https://api.simplylookupadmin.co.uk.
I would suggest on key up event, of this textbox, if user stops typing for 300 ms call
"https://api.simplylookupadmin.co.uk/full_v3/getaddresslist?data_api_Key=APIKEY&query=texttosearch&options=B" to
populate a selection box called "listBoxAddressLines".
Example. If texttosearch="PE13 2QL", this API call will return json
"{
"results":
[
{
"Line": "1 Victoria Road Wisbech PE13 2QL",
"ID": "11570811_0S"
},
{
"Line": "10 Victoria Road Wisbech PE13 2QL",
"ID": "11570812_0S"
},
{
"Line": "Victoria Lodge 18 Victoria Road Wisbech PE13 2QL",
"ID": "31597197_2535693S"
}
],
"inputid": 0,
"queryid": 0,
"processResult": true,
"instructionsHtml": "Now enter House Name or Number."
"instructionsTxt": "Now enter House Name or Number."
"finishword": ""
"errormessage": ""
}" display this for user selection, and then if the user selects a line, call full_v3/getselectedaddress
with api key and ID of line selected. And update "labelInstructions" label with "instructionsHtml" from the json results.
Also, if one line is returned in the results, and the user tabs out of the "textBoxFind" text box, we make it select first item as if the user selected it.
And the in the results line Bold the text marked with HTML "" starts the bold and "" ends the Bold.
When the user selects a line in the results, the API call full_v3/getselectedaddress?data_api_Key=APIKEY&id=Selected line id, will return json
"{
"found": true,
"error": false,
"inputid": 0,
"licenseStatus": "DEMO Full Address Data for ZZ until ('08 Dec 2024')",
"addressID": "",
"organisation": "",
"line1": "The Limes",
"line2": "27 Victoria Road",
"line3": "",
"town": "Wisbech",
"county": "Cambridgeshire",
"postcode": "PE13 2QL",
"rawpostcode": "PE132QL",
"country": "England",
"deliverypointsuffix": "1T",
"nohouseholds": "1",
"smallorg": "N",
"pobox": "",
"mailsortcode": "51144",
"unique1": "The Limes",
"unique2": "27",
"propertyNo": "27",
"propertyName": "The Limes",
"streetName": "Victoria Road",
"udprn": "18616525",
"userid": "",
"geoposition": "52.659857,0.1617",
"geolongitude": 0.1617,
"geolatitude": 52.659857,
"geodistanceinkm": 0,
"geodistanceinmiles": 0
}"
Then, put the returned address fields "organisation,line1,line2,line3,town,county,postcode,
country,found,licenseStatus" into a multiline textbox called "textBoxAddress."
When this was working, we then asked:
Generate Example in Chat GPT or Similar That's great, can we make "listBoxAddressLines" hidden, and only shown when a search is in progress, also initially set labelInstructions to "Type Postcode, Postcode + Part of address or words to search"
Other Refinements
Change the address mapping to your address fields. Data Returned by getselectedaddress
On the first call full_v3/getaddresslist Info on getaddresslist
1. queryid - If you are implementing search as you type, you can supply a counter in this parameter, which is returned. This allows you to process the most recent query results and ignore any
older responses.
2. inputid - If you have multiple address forms, you can give each a number, which is returned in the response. Then your response code can then act appropriately.
On the last call full_v3/getselectedaddress Info on getselectedaddress
1. homelocation - if set to a valid postcode, or 'lat,long', it will calculate the distance from the Address
2. inputid - If you have multiple address forms, you can give each a number, which is returned in the response. Your response code can act appropriately.
3. userid - If used within an organisation by employees of a company with a user-based license, then this should identify the call for data used to count the users. User Name or GUID relating to the user. (must be 8 Chars or More). This is a requirement of the Royal Mail Terms & Conditions. Not required if credit packs are purchased.
These API JSON web service calls are discussed in detail below:
Address Finder API Functions
Call 1 - Get Address List
The getaddresslist() API Function gets the list of addresses matching what is typed by the user.
getaddresslist() Required Parameters
| Parameter name | Description |
|---|---|
| data_api_Key | Data Key / API key obtained from your online account. API Key offers more protection since API key can be locked to a specified domain of origin. |
| query | Postcode, Postcode + Part of address or words (search as you type) to query |
getaddresslist() Optional Parameters
| Parameter name | Description |
|---|---|
| userid | If used within an organisation by employees of a company with a user-based license, then this should identify the call for data used to count the users. User Name or GUID relating to the user. (must be 8 Chars or More) |
| options | Options, B-Bold matching words. |
| custid | If you are a reseller, you can use your own API key and supply the end customer's license ID, which is allocated when the customer is created in your reseller online account. The query will then be charged to the end-user. |
| queryid | If you are implementing search as you type, you can supply a counter in this parameter, which is returned. This allows you to process the most recent query results and ignore any older responses. |
| inputid | If you have multiple address forms, you can give each a number, which is returned in the response. Then your response code can then act appropriately. |
| country | Future Dev. |
getaddresslist() Example
User types in Postcode, Postcode + Part of address or words (search as you type).
Then presses Find button, or you implement a timer based on key up event to fire query 300ms after the last key up event
getaddresslist() is called to get the list to present to user
Open API Web Service - Get List
user searches for "PE13 2QL"
https://api.simplylookupadmin.co.uk/full_v3/getaddresslist?data_api_Key=YOUR API KEY&query=pe13%202ql
Returns json
{
"results": [
{
"Line": "1 Victoria Road Wisbech PE13 2QL",
"ID": "11570811_0S"
},
{
"Line": "10 Victoria Road Wisbech PE13 2QL",
"ID": "11570812_0S"
},
And so on...
{
"Line": "The Limes 27 Victoria Road Wisbech PE13 2QL",
"ID": "11570825_0BN"
},
{
"Line": "Victoria Lodge 18 Victoria Road Wisbech PE13 2QL",
"ID": "31597197_2535693S"
}
],
"inputid": 0,
"queryid": 0,
"processResult": true,
"errormessage": ""
}
getaddresslist() Returns
| Name | Description |
|---|---|
| errormessage | Contains a message if error occurred when searching for Address |
| processResult | Boolean : True if result should be processed |
| queryid | Return the queryid given in parameter. If you have multiple address forms, you can give each a number, which is returned in the response. Then your response code can then act appropriately. |
| inputid | Return the inputid given in parameter. If you have multiple address forms, you can give each a number, which is returned in the response. Then your response code can then act appropriately. |
| results | Array of lines (ID, Line) to display. |
| instructions | Provides a string of HTML to display as a user types and progresses through a search. This is the top line in our demo Try Demo Address Finder as Disussed |
| instructionsTxt | Same as instructions but simple text |
| finishword | If Tab to complete, then chars to complete sentance |
Call 2 - Get Selected Address
User selects from list. The Line ID is then used to get Full Address details + GeoLocation from getselectedaddress()
getselectedaddress() Required Parameters
| Parameter name | Description |
|---|---|
| data_api_Key | Data Key / API key obtained from your online account. API Key offers more protection since API key can be locked to a specified domain of origin. |
| id | ID of Address selected by user |
getselectedaddress() Optional Parameters
| Parameter name | Description |
|---|---|
| userid | If used within an organisation by employees of a company with a user-based license, then this should identify the call for data used to count the users. User Name or GUID relating to the user. (must be 8 Chars or More) |
| homelocation | Home Postcode or 'lat,long' to calculate the distance from Address |
| custid | If you are a reseller, you can use your own API key and supply the end customer's license ID, which is allocated when the customer is created in your reseller online account. The query will then be charged to the end-user. |
| inputid | If you have multiple address forms, you can give each a number, which is returned in the response. Then your response code can then act appropriately. |
getselectedaddress() Example
User selects from list. The Line ID is then used to get Full Address details + GeoLocation from getselectedaddress()
Open API Web Service - Get Selected Address
user selects first item from list, and we also get distance from big ben SW1A0AA
https://api.simplylookupadmin.co.uk/full_v3/getselectedaddress?data_api_Key=YOUR API KEY&id=11570811_0S&homelocation=SW1A0AA
Returns json
{
"found": true,
"error": false,
"inputid": 0,
"licenseStatus": "Full PAF 2/2 users",
"addressID": "",
"organisation": "",
"line1": "1 Victoria Road",
"line2": "",
"line3": "",
"town": "Wisbech",
"county": "Cambridgeshire",
"postcode": "PE13 2QL",
"rawpostcode": "PE132QL",
"country": "England",
"deliverypointsuffix": "1A",
"nohouseholds": "1",
"smallorg": "N",
"pobox": "",
"mailsortcode": "51144",
"unique1": "1",
"unique2": "",
"propertyNo": "1",
"propertyName": "",
"streetName": "Victoria Road",
"udprn": "18616510",
"userid": "",
"geoposition": "52.659857,0.1617",
"geolongitude": 0.1617,
"geolatitude": 52.659857,
"geodistanceinkm": 130.52,
"geodistanceinmiles": 81.1
}
Data Returned by getselectedaddress()
After the address is selected by the user, the Web Address Finder returns the following data.
Data Returned by Address Finder
For 99% of our customers, they only need the following core address data:
| Name | Description |
|---|---|
| organisation | Organisation if a company or organisation. |
| line1 | Line 1 of address, always contains data. |
| line2 | Line 2 of address, not always filled in. |
| line3 ★ | Line 3 of address, not always filled in. |
| town | Town. Always filled in. |
| county ★ | County, not always filled in. |
| postcode | Formated Postcode. If the 'Taxi Locations' option is ON, then Trains and Bus Stations will return UNKOWN since they have no Postcode. 'Taxi Locations' are intended to get GeoLocation for booking Taxis. |
| country | England, Scotland, Wales... |
★ - Not required by the Royal Mail to send letters and parcels.
License Status
The current License status, or error is returned:
| Name | Description |
|---|---|
| error | BOOLEAN : true if error, else false |
| licenseStatus | Status of license, or Error if error. Not shown if public site. |
GeoLocation
The GeoLocation is returned if known within 100 meters. The Open API will also return straight line distance if a home location is specified (Lat/Long or valid postcode):
| Name | Description |
|---|---|
| geodistanceinkm | Distance from homelocation in km. homelocation is either set in SimplyComplete Class or under the 'SimplyCompleteAI' tab in your online account. |
| geodistanceinmiles | Distance from homelocation in miles. homelocation is either set in SimplyComplete Class or under the 'SimplyCompleteAI' tab in your online account. |
| geoposition | 'Lat,Long' of Address within 100m |
| geolatitude | Lat within 100m |
| geolongitude | Long of Address within 100m |
Additional Data
The Simply Postcode PAF database contains some additional data returned as follows:
| Name | Description |
|---|---|
| rawpostcode | Postcode as stroed in PAF. 7 chars long |
| 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 a unique ID. |
| nohouseholds | Number of house holds at this postcode address |
| smallorg | Y = Small Organisation |
| pobox | PO Box number if PO Box address |
| mailsortcode | The Royal Mail offer discount if mail is sorted by this code |
| udprn | Unique 8 digit code assigned to each addressable property (Delivery Point). |
| unique1 unique2 |
Gives the unique portion of the address record. Can be 2 lines. |
| propertyNo | Property Number, if an address is a simple number in a street. |
| propertyName | Property Name. This can contain two lines separated by "," A number like "1-3","3A" are treated as names (see below) |
| streetName | Name of street. |
Additional Data Example Postcode SW11 1QG returns address:
Flat 6
Carrington Court
21 Limburg Road
London
SW11 1QG
United Kingdom
unique1 returns "Flat 6"
unique2 returns "Carrington Court"
PropertyNo returns "21"
PropertyName returns "Carrington Court"
StreetName returns "Limburg Road"