Desktop Software Development Kit (SDK)

Request trial

Please note you can use a FREE trial version to integrate into your application before you purchase.
This will include the postcode.dll file and other associated files.

Need help?... Ask the experts

Our developers are on hand to answer any questions you may have before or after signing up. Contact them today

Integrating PostcodeSoftware

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 Installation

Check_expire_date also returns and integer value named days_left which shows how many days are left until the licence 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 licence 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

5. Days Remaining: Checks How many licenced days remain.

Function Name: days_remaining()
Return Type: Short
Returns: total days remaining

Lookup Address

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.

Towns Functions

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 ";"]

Counties Function

1. 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 "|" ]

Postcode Function

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

Premise Functions (Premise Level Product only)

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.

VB.NET Examples

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

VB.6 Examples

Add reference

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.
If this option is not available, click on the browse button, browse to C:\PostcodeSoftware and double click on Postcode.tlb

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

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_premises("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 postcod

Dim addressobj As New Postcode.Address
Dim addresslist As string
addresslist = addressobj.Get_address_list_postcode_premises("LS18 4AA","","")

Licensing

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

Distribution

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 licence fee. Payment must be made for each user of the software.

You can contact us as follows:-

PostcodeSoftware, 1st Floor Osborne House, 20 Victoria Avenue, Harrogate, HG1 5QY

Tel: 0845 83 82 666 // Email: info@postcodesoftware.com

Desktop Software Development Kit (SDK)

Functions

Integrating PostcodeSoftware

Check Installation

Lookup Address

Towns Functions

Counties Function

Postcode Function

Premise Functions (Premise Level Product only)

Exampe code

VB.NET Examples

Return an address from a postcode

Check Installation

Return list of addresses from County details

Return list of addresses from a partial Postcode

Return list of addresses from town details

Premise Examples

VB.6 Examples

Add reference

Return an address from a postcode

Check installation

Return list of addresses from county details

Return list of addresses from a partial postcode

Return list of addresses from town details

Premise Examples

Licensing

Distribution