The SDK is essentially a library of functions which access the PostcodeSoftware database.  This document will guide you through the functions available and the steps needed to integrate to your own applications.  Example code is given for VB.NET, C#.NET and VB6.  PostcodeSoftware can be integrated into larger applications using the Postcode.dll file and can also be accessed as a com object.  Postcode.dll is registered in the Global Assembly Cache (GAC) on installation.

PostcodeSoftware must be installed and fully activated for both developer and end user for integration to be successful.

Integrating with VB.NET or C#.NET requires a reference to C:\PostcodeSoftware\Postcode.dll.  In VB6 Postcodesoftware will appear in your list of references. 

A function is available to check if PostcodeSoftware is installed and activated.  An error will be returned when referencing Postcode.dll if PostcodeSoftware is not installed.  There is a Function available to check if the PostcodeSoftware licence has expired; all functions have the check embedded in them and will return a message if the licence has expired.

Check_expire_date also returns and integer value named days_left which shows how many days are left until the license expires.

1. Check if Installed: Checks if PostcodeSoftware is installed and activated on the computer.

Function Name: check_installation()
Return Type: Short
Returns: 1 = Installed, 0 =Installed but not Activated, (Returns an Error if Not Installed)

2. Check mode: Checks if PostcodeSoftware is in demo mode or the full working version.

Function Name: checkmode()
Return Type: Short
Returns: 1 = Demo Mode, 2 = Full Mode

3. Check Expiration Date: Checks the expiration date of the software.

Function Name: check_expire_date ()
Return Type: Short
Returns: 0 = Expired, 1 = Valid
Returns: days_left as Integer (number of days left until the license expires.)

4. Check Product: Checks if street level or premise level PostcodeSoftware is installed.

Function Name: check_product ()
Return Type: Short
Returns: 1 = Street Level, 2 = Premises Level

An address record is returned from the function Getaddress_string()

1. Get address: Returns the address of a given postcode in a string format.
Function Name: Getaddress_string()
Parameters: Postcode = String
Return Type: String
Returns: String [Each part of address separated by ";" 10 values in total]
Returned values:
1.dependent thoroughfare;
2.dependent thoroughfare descriptor;
3.thoroughfare;
4.thouroghfare descriptor;
5.double dependent locality;
6.dependent locality;
7. town;
8.county;
9.postcode;
10.county required (0 = not required, 1 = required );

e.g. ;;South;Row;;Horsforth;Leeds;West Yorkshire;LS18 4AA;0; will be returned for postcode LS18 4AA
a blank value will be returned for any values not in the address. The address above does not have a dependent thoroughfare or dependent thoroughfare descriptor. It also does not have a double dependent locality. The 0 in the county required field means that the county is not required to be shown for the address.

1. Structure: towns: The structure contains functions to list towns and get address and postcode details from a town.
Consists of:

count = Integer
address_count = Integer
Get_address_list_town() = Function
Get_locality_list() = Function
Get_town_list() = Function

2. Get address List from town: Gets all postcodes and addresses for a given locality id.

Function Name: Get_address_list_town()
Parameters: locality_id = String
Return Type: String
Returns: String [Each part of address separated by ";" ( same format as Getaddress_string) and Each address separated by "|"]

3. Get locality list from town: Gets a list of localities id's from a given town.

Function Name: Get_locality_list()
Parameters: Post Town = String, Optional dependent_locality = String, optional double_dependent_locality = String
Return Type: String
Returns: String [Each Locality id separated by "|" ]

4. Get a list of towns: Gets a list of all the towns in the PostcodeSoftware database.

Function Name: Get_town_list()
Return Type: String
Returns: String [Each Town separated by "|" ]

5. Get a list of dependent and double dependent localities: Gets a list of all the towns dependent and double dependent locality information from the PostcodeSoftware database.

Function Name: Get_dependent_localities()
Return Type: String
Returns: String [Each dependent locality, double dependent locality separated by ";"]

1. Structure: counties: Contains functions to get a list of outward codes for a county, a list of postcodes and addresses and postcodes for an outward code and a list of counties.

Consists of:
count = Integer
address_count = Integer
Get_county_outward_list() = Function
Get_county_list() = Function
Get_address_list_county() = Function

2. Get list of Counties: Returns a list of all the counties in the PostcodeSoftware database.

Function Name: Get_county_list()
Parameters: Post Town = String
Return Type: String
Returns: String [Each County separated by "|" ]

1. Gets address list from a partial Postcode: Returns a list of all addresses and postcodes for a partial postcode.

Function Name: Get_address_list_postcode()

Parameters: PostCode= String, Thoroughfare = String, Thoroughfare_descriptor = String
Return Type: String
Returns: String [Each part of address separated by ";" and Each address separated by "|"]

1. Gets the premises information for a postcode.

Function Name: Get_premises()
Parameters: Postcode = String, Optional include_organisation = boolean (default = false)
Return Type: String
Returns: String [Each premises separated by ";" formatted "organisation|building details|number;"]

2. Gets a list of addresses to premises level for towns and streets.

Function Name: Get_address_premisis_list()
Parameters: Town = String, dependent_locality = String, double_dependent_locality = String, double_dependent_locality = String, thoroughfare = String, thoroughfare_descriptor = String
Return Type: String
Returns: String [Each part of address separated by ";" 11 values in total, each address separated by "|"]
Returned values:
1.premise data. (Each part separated by "/" denoting a carriage return in the address)
2.dependent thoroughfare;
3.dependent thoroughfare descriptor;
4.thoroughfare;
5.thouroghfare descriptor;
6.double dependent locality;
7.dependent locality;
8. town;
9.county;
10.postcode;
11.county required (0 = not required, 1 = required );

e.g.15;;;South;Row;;Horsforth;Leeds;West Yorkshire;LS18 4AA;0| will be returned for Get_address_premises_list("Leeds","Horsforth","","south","row")
a blank value will be returned for any values not in the address.

3. Gets a list of addresses to premises level for a postcode or partial postcode.

Function Name: Get_address_list_postcode_premises()
Parameters: Pcode = String, thoroughfare = String, thoroughfare_descriptor = String
Return Type: String
Returns: String [Each part of address separated by ";" 11 values in total, each address separated by "|"]
Returned values:
1.premise data. (Each part separated by "/" denoting a carriage return in the address)
2.dependent thoroughfare;
3.dependent thoroughfare descriptor;
4.thoroughfare;
5.thouroghfare descriptor;
6.double dependent locality;
7.dependent locality;
8. town;
9.county;
10.postcode;
11.county required (0 = not required, 1 = required );

e.g.15;;;South;Row;;Horsforth;Leeds;West Yorkshire;LS18 4AA;0| will be returned for Get_address_list_postcode_premises("LS184AA","","")
a blank value will be returned for any values not in the address.

Return an address from a postcode

1. Return an address string for a given postcode.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim address As string

'Call Getaddress_string function

address = addressobj.Getaddress_string("LS18 4AA ")

Check Installation

1. Check if PostcodeSoftware is installed and activated.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim status As short

'Call check_installation function

status = addressobj.check_installation()

Note: an error will be returned if PostcodeSoftware is not installed.

2. Check PostcodeSoftware mode

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim status As short

'Call checkmode function

status = addressobj.checkmode()

3. Check when PostcodeSoftware expires

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim status As short

'Call checkmode function

status = addressobj.check_expire_date()

Return list of addresses from County details.

1. Get list of counties.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim addressobj As New Postcodesoftware.Address

Dim countylist As String

'Call Get_county_list function

countylist = addressobj.Get_county_list

Return list of addresses from a partial Postcode.

1. Get list of addresses for a partial Postcode.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim addresslist As String

Dim addressobj As New Postcodesoftware.Address

'Call Get_address_list_county function

addresslist = addressobj.Get_address_list_postcode("LS18","","")

Return list of addresses from town details.

1. Get list of towns.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim townlist As String

Dim addressobj As New Postcodesoftware.Address

'Call Get_town_list function

townslist = addressobj.Get_town_list

2. Get list of localities for a town.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim localitylist As String

Dim addressobj As New Postcodesoftware.Address

'Call Get_locality_list function

localitylist = addressobj.Get_locality_list("LEEDS")

3. Get list of addresses for a locality.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim addresslist As String

Dim addressobj As New Postcodesoftware.Address

'Call Get_address_list_town function

addresslist = addressobj.Get_address_list_town("24878")

4. Get list of dependent and double dependent localities for a town

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

Dim Localities As String

Dim addressobj As New Postcodesoftware.Address

'Call Get_address_list_town function

Localities = addressobj.Get_dependent_localities("LEEDS")

Premise Examples

1. Return Premise details for a given postcode.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim premise As string

'Call Get_premises function

premise = addressobj.Get_premises("LS18 4AA")

2. Return a list of addresses from a town/street.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim addresslist As string

'Call Get_address_premises_list function

addresslist = addressobj.Get_address_premises_list("LEEDS","Horsforth","","South","Row")

3. Return a list of addresses from a postcode/partial postcode.

'Add a reference to Postcode.dll

'Add imports

Imports Postcodesoftware

Imports Postcodesoftware.Address

'Declare object

Dim addressobj As New Postcodesoftware.Address

Dim addresslist As string

'Call Get_address_list_postcode_premises function

addresslist = addressobj.Get_address_list_postcode_premises("LS18 4AA","","")

For the PostcodeSoftware functions to work you firstly need to add a reference to PostcodeSoftware.co.uk.
Go to the Project dropdown menu and select References.
Scroll down the list and tick the option called PostcodeSoftware.co.uk and click ok.

Return an address from a postcode

1. Return an address string for a given postcode.
Dim addressobj As New Postcode.Address
Dim address As string
address = addressobj.Getaddress_string("LS18 4AA")

Check Installation

1. Check if PostcodeSoftware is installed and activated.
Dim addressobj As New Postcode.Address
Dim status As integer
status = addressobj.check_installation()
Note: An error will be returned if PostcodeSoftware is not installed.

2. Check PostcodeSoftware mode
Dim addressobj As New Postcode.Address
Dim status As integer
status = addressobj.checkmode()

3. Check when PostcodeSoftware expires
Dim addressobj As New Postcode.Address
Dim status As integer
status = addressobj.check_expire_date()

Return list of addresses from County details.

1. Get list of counties.
Dim countylist As String
Dim Address As New Postcode.Address
countylist = Address.Get_county_list

Return list of addresses from a partial Postcode.

1. Get list of addresses for a partial postcode.
Dim addresslist As String
Dim Address As New Postcode.Address
addresslist = Address.Get_address_list_postcode("LS18","","")

Return list of addresses from town details.

1. Get list of towns.
Dim townlist As String
Dim Address As New Postcode.Address
townlist = Address.Get_town_list

2. Get list of localities for a town.
Dim localitylist As String
Dim Address As New Postcode.Address
localitylist = Address.Get_locality_list("LEEDS")

3. Get list of addresses for a locality.
Dim addresslist As String
Dim Address As New Postcode.Address
addresslist = Address.Get_address_list_town("2")

4. Get list of dependent and double dependent localities for a town
Dim Localities As String
Dim Address As New Postcode.Address
Localities = Address.Get_dependent_localities("LEEDS")

Premise Examples

1. Return Premise details for a given postcode.
Dim addressobj As New Postcode.Address
Dim premise As string
premise = addressobj.Get_premise("LS18 4AA")

2. Return a list of addresses from a town/street.
Dim addressobj As New Postcode.Address
Dim addresslist As string
addresslist = addressobj.Get_address_premises_list("LEEDS","Horsforth","","south","row")

3. Return a list of addresses from a postcode/partial postcode.
Dim addressobj As New Postcode.Address
Dim addresslist As string
addresslist = addressobj.Get_address_list_postcode_premises("LS18 4AA","","")

Add Reference

For the PostcodeSoftware functions to work you firstly need to add a reference to postcode.dll.
In visual studio go to the Project dropdown menu and select Add Reference.
On the screen that appears click on the Browse tab and navigate to the PostcodeSoftware installation folder.
Select the file called Postcode.dll and click ok.

Return an address from a postcode

1. Return an address string for a given postcode.
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
String address;
address = addressobj.Getaddress_string("LS18 4AA") ;

Check Installation

1. Check if PostcodeSoftware is installed and activated.
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
Short status;
status = addressobj.check_installation()
Note: An error will be returned if PostcodeSoftware is not installed. ;

2. Check PostcodeSoftware mode
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
Short status;
status = addressobj.checkmode();

3. Check when PostcodeSoftware expires
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
Short status;
status = addressobj.check_expire_date();

Return list of addresses from County details.

1. Get list of counties.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String countylist;
PostcodeSoftware.Address Address;
countylist = Address.Get_county_list;

2. Get list of outward codes for a county.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String outwardlist;
PostcodeSoftware.Address Address;
outwardlist = Address.Get_county_outward_list("North Yorkshire ");

Return list of addresses from a patrial postcode.

1. Get list of addresses for a partial postcode.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String addresslist;
PostcodeSoftware.Address Address;
addresslist = Address.Get_address_list_postcode("LS18","","");

Return list of addresses from town details.

1. Get list of towns.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String townlist;
PostcodeSoftware.Address Address;
townlist = Address.Get_town_list;

2. Get list of localities for a town.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String localitylist;
PostcodeSoftware.Address Address;
localitylist = Address.Get_locality_list("LEEDS");

3. Get list of addresses for a locality.
using PostcodeSoftware;
using PostcodeSoftware.Address;
String addresslist;
PostcodeSoftware.AddressAddress;
addresslist = Address.Get_address_list_town("2");

4. Get list of dependent and double dependent localities for a town
using PostcodeSoftware;
using PostcodeSoftware.Address;
String Localities;
PostcodeSoftware.Address Address;
Localities = Address.Get_dependent_localities("LEEDS");

Premise Examples

1. Return Premise details for a given postcode.
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
String premise;
premise = addressobj.Get_premise("LS18 4AA") ;

2. Return a list of addresses from a town/street.
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
String addresslist;
addresslist = addressobj.Get_address_premises_list("LEEDS", "horsforth", "", "south", "row") ;

3. Return a list of addresses from a postcode/partial postcode.
using PostcodeSoftware;
using PostcodeSoftware.Address;
PostcodeSoftware.Address addressobj;
String addresslist;
addresslist = addressobj.Get_address_list_postcode_premises("LS18 4AA","","") ;

Add Reference

For the PostcodeSoftware functions to work you firstly need to add a reference to PostcodeSoftware.co.uk.
Go to the Tools menu, select Macro, then select Visual Basic Editor.
In the Visual Basic editor go to the Tools menu and select References.
Scroll down the list and tick the option called PostcodeSoftware.co.uk and click ok.

The code below is used in the sample Access application and can be downloaded from the following link.
http://www.postcodesoftware.co.uk/download/PostcodeSoftwareExample.zip (Street Level)

Save the file to disk, unzip the file and double click on the PostcodeSoftwareExample.mdb file

Dim Address As New Postcode.Address
Private Sub Fill_Click()
Dim strAaddress As String
Dim Lines
Dim nLines As Integer
ErrorMsg = ""
If IsNull(txtPostcode) Then
ErrorMsg = "No Postcode entered"
Exit Sub
End If
If Len(Trim(txtPostcode)) < 6 Then
ErrorMsg = "Postcode must be at least 6 characters long"
Exit Sub
End If
strAddress = Address.Getaddress_string(txtPostcode)
' Split returned address by semi-colons into an array
Lines = Split(strAddress, ";")
nLines = UBound(Lines)
If nLines = 0 Then
ErrorMsg = strAddress
Exit Sub
End If
txtPostcode = ""
txtPostcode.SetFocus
Address1 = Lines(0) + IIf(Lines(0) = "" And Lines(1) = "", "", " ") + Lines(1)
Address2 = Lines(2) + IIf(Lines(2) = "" And Lines(3) = "", "", " ") + Lines(3)
Address3 = Lines(4)
Address4 = Lines(5)
AddressTown = Lines(6)
AddressCounty = Lines(7)
AddressPostcode = UCase(Lines(8))
End Sub

The license for the use of the data supplied with the PostcodeSoftware SDK runs for one year from the date of purchase.  The license is based on each user.

Once you have completed development, you will want to distribute PostcodeSoftware as part of your own program.  Your purchase of the PostcodeSoftware SDK entitles you to use the library functions and the data on the development machine only.  The data remains the copyright of the Royal Mail, who require that it be updated annually together with the payment of a license fee. Payment must be made for each user of the software.

You can contact us as follows:-

PostcodeSoftware
Ashbourne House
2 South Park Road
Harrogate
HG1 5QU

Tel:    0845 83 82 666
Email: info@postcodesoftware.co.uk