The Search Premise functions allow you to search for Address Premises. An Address Premise is a Unique Delivery Point and a search will return a collection of 'List Address' and Unique_Identifiers for all the delivery points for the criteria in the search. These functions are used in conjunction with the 'Get Address' functions.
Example: Use the SearchPremise_ByPostcode function to return a list of Premise Addresses for a known postcode (zero credits). Select the Address from the list and return the Full Premise Address using the GetPremiseAddress function (1 credit).
These searches are useful when you have specific search criteria like a full Postcode or Street Name, Number and Town.
There are currently 28,000,000+ Unique Premise Delivery Points.
The List below describes the functions available (zero credits used in search):
*Try not to search on 'Noise' words ONLY. e.g. 'street', 'bank', 'house', etc as this will result in a 302 error being returned.
Always be as specific as possible e.g. street='high st', town='glasgow' as this will speed up response times.
| Function Name |
Function Description |
| SearchPremise_ByPostcode |
This search takes 4 parameters and returns a collection of ListAddressPremise objects.
The 'Postcode' parameter must be entered.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
| SearchPremise_ByPostcode_Dataset |
This search is the same as SearchPremise_ByPostcode but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. |
| SearchPremise_ByStreet |
This search takes 6 parameters and returns a collection of ListAddressPremise objects. The 'Street' parameter must be entered. The 'Number' parameter is optional.
The 'Town' parameter is optional.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. * |
| SearchPremise_ByStreet_Dataset |
This search is the same as SearchPremise_ByStreet but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. * |
| SearchPremise_ByThoroughfareID |
This search takes 4 parameters and returns a collection of ListAddressPremise objects. The 'ThoroughfareID' parameter must be entered.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank.
This search is used in conjnction with the SearchThoroughfare_By... functions. |
| SearchPremise_ByThoroughfareID_Dataset |
This search is the same as SearchPremise_ByThoroughfareID but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. |
| SearchPremise_ByOrganisation |
This search takes 5 parameters and returns a collection of ListAddressPremise objects. The 'Organisation' parameter must be entered. The 'Town' parameter is optional.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank.* |
| SearchPremise_ByOrganisation_Dataset |
This search is the same as SearchPremise_ByOrganisation but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. * |
| SearchPremise_ByPOBox |
This search takes 5 parameter and returns a collection of ListAddressPremise objects. The 'POBox' parameter must be entered.
The 'Town' parameter is optional.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
| SearchPremise_ByPOBox_Dataset |
This search is the same as SearchPremise_ByPOBox but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. |
| SearchPremise_ByWordMatchOnAll |
This search takes 4 parameters and returns a collection of ListAddressPremise objects.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank.
The word match is carried out on the POBox, Organisation_Department, Organisation, Sub_Building_Name, Building_Name, Dependent_Street, Street, Double_Dependent_Locality, Dependent_Locality, Posttown and Postcode fields.
You can enter multiple search criteria by separating them with commas.
e.g. Search on 'etellect ltd,etellect house' will search the above fields for the phrase 'etellect ltd' AND 'etellect house'.* |
| SearchPremise_ByWordMatchOnAll_Dataset |
This search is the same as SearchPremise_ByWordMatchOnAll but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table.* |
A formal description of the services can be found in the 'Service Description' section of http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above functions returns a collection of List Address Premises either as a dataset or List depending on the method invoked.
The Geographic functions return geographics information for a postcode or list of postcodes.
Example: These functions can be used on a website to show locations of postcodes on multimap or google maps.
The information returned includes UK Grid 100 m References, Ordnance Survey Longitude and Latitude, Local Or Unitary Authority Names, Ward Names and Codes, NHS Primary Care Trust names and codes, NHS Strategic Health Authority or Health Board Names and Codes + Regional Offices, Multimap Links.
The List below describes the functions available:
| Function Name |
Function Description |
| GeoData_ForPostcode |
This function takes 4 parameters and returns a collection of Geographic objects.
The 'Postcode' parameter must be entered. (This field can either be a single postcode or alist of postcodes separated with commas).
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
| GeoData_ForPostcode_Dataset |
This search is the same as GeoData_ForPostcode but returns the data as a PostcodeUtilities dataset with a populated Geographic table. |
A formal description of the services can be found in the 'Service Description' section of
http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above functions returns a collection of Geographic objects either as a dataset or List depending on the method invoked.
The GetPremiseAddress functions return the full Postal Address of a Premise based on the Unique Delivery Point ID.
This function is usually used in conjunction with the SearchPremise_By.... functions.
Example: Run a search on postcode using the SearchPremise_ByPostcode function (returns a list of premises) (zero credits). Select the correct premise from list - Use the GetPremiseAddress function to return the full address details (1 credit).
The List below describes the functions available:
| Function Name |
Function Description |
| GetPremiseAddress |
This search takes 4 parameter and returns a collection of AddressPremise objects.
The 'Unique Delivery Point ID' parameter must be entered.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
| GetPremiseAddress_Dataset |
This search is the same as GetPremiseAddress but returns the data as a PostcodeUtilities dataset with a populated AddressPremise table. |
A formal description of the services can be found in the 'Service Description' section of
http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above functions returns a collection of Address Premises either as a dataset or List depending on the method invoked.
The Nearest functions return information about the distance between a datum postcode and a single reference postcode or list of reference postcodes.
Example: Use these functions as a 'Store Locator'. A user enters his/her postcode and is given information on the nearest store(s) to his/her location.
The information returned includes distances measured in metres, kilometres, miles and nautical miles. If a list of check postcodes are being queried the Ordinal_Position field returns the closest postcode to the datum. 0 being the closest, 1 next closest, 2 next, etc.
The List below describes the functions available:
| Function Name |
Function Description |
| DistanceBetween_Postcodes |
This function takes 5 parameters and returns a collection of Nearest objects.
The 'Postcode Datum' parameter must be entered.
The 'Postcode Check' parameter must be entered. (Either as a single postcode or list of postcodes separated by comma).
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
| DistanceBetween_Postcodes_Dataset |
This search is the same as DistanceBetween_Postcodes but returns the data as a PostcodeUtilities dataset with a populated Nearest table. |
| NearestData_ForPostcode |
This function takes 7 parameters and returns a collection of Nearest objects.
The 'Postcode Datum' parameter must be entered.
The 'Postcode Check' parameter must be entered. (Either as a single postcode or list of postcodes separated by comma).
The 'Postcode Descriptions' parameter is optional, this is a meaningful description for the postcode entered. (If this parameter is entered it must have the same number of entries as the 'Postcode Check' field otherwise a 301 error will be returned).
The 'Number to Return' parameter is optional. If this is left blank only 1 nearest record will be returned. Otherwise enter the number of records you want returned.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank.
e.g. PostcodeDatum='G52 4BN'
PostcodeCheck='G99 1AA,ML77 5GG,HA56 6TT'
PostcodeDescriptions='Head Office,Sales Office,Depot'
NumberToReturn='2'
This will return the 2 nearest records for the 2 closest Postcodes in the PostcodeCheck fileld to the PostcodeDatum. |
| NearestData_ForPostcode_Dataset |
This search is the same as NearestData_ForPostcode but returns the data as a PostcodeUtilities dataset with a populated Nearest table. |
A formal description of the services can be found in the 'Service Description' section of
http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above functions returns a collection of Nearest objects either as a dataset or List depending on the method invoked.
A Return Code is included in every record returned to the user when a call is made to the functions of the ePostcode web service (except ServiceTest).
These Return Codes can be used to get information about any errors or data input problems that may have occurred.
N.B. The web service functions will always return at least one record. If the Return Code is not "1" in the first record then there is a problem.
The table below lists these Return Codes:
| Return Code |
Description |
| 0 |
Zero Records Returned.
e.g. Searching Premises for a postcode that does not exist. |
| 1 |
Success |
| 2 |
Internal Error |
| 201 |
Invalid Account Details Entered |
| 203 |
Not Enough Credits Available To Complete Request |
| 301 |
User Input Not Correctly Formatted |
| 302 |
User Search Criteria Is Too Vague or Search Carried Out On 'Noise' Words ONLY (i.e. Searching for 'street' or 'road', the search should contain the name of the street 'High Street' or 'Main Road'). |
The Search Thoroughfare functions allow you to search for Address Thoroughfares. An Address Thoroughfare is a Unique Street and Locality Location and a search will return a collection of 'List Address' and Unique_Identifiers for all the thoroughfares for the criteria in the search. These functions are used in conjunction with the 'Search Premise' and 'Get Address' functions.
Example: Use the SearchThoroughfare_ByStreet function to return a list of Thoroughfares for a known street name (zero credits). Use the SearchPremise_ByThoroughfareID function to return a list of Premise Addresses for the selected thoroughfare(zero credits). Select the Address from the list and return the Full Premise Address using the GetPremiseAddress function (1 credit).
This search is useful when a search criteria is vague and a Search on Premise would return too many Premises. e.g. You want all streets in the postcode district 'G52' or you know the name part of the street name.
This search can be used in conjunction with the SearchPremise_ByThoroughfareID and SearchPremise_ByThoroughfareID_Dataset functions.
The List below describes the functions available:
*Try not to search on 'Noise' words ONLY. e.g. 'street', 'bank', 'house', etc as this will result in a 302 error being returned.
Always be as specific as possible e.g. street='high st', town='glasgow'.
| Function Name |
Function Description |
| SearchThoroughfare_ByPostcodeDistrict |
This search takes 1 parameter and returns a collection of ListAddressThoroughfare objects.
The 'Postcode District' parameter must be entered.
The Postcode District is the part of a Postcode before the space.
e.g. G52 4NQ - Postcode District is G52 |
| SearchThoroughfare_ByPostcodeDistrict_Dataset |
This search is the same as SearchThoroughfare_ByPostcodeDistrict but returns the data as a PostcodeUtilities dataset with a populated ListAddressThoroughfare table. |
| SearchThoroughfare_ByStreet |
This search takes 3 parameters and returns a collection of ListAddressThoroughfare objects. The 'Street' parameter must be entered. The 'Number' parameter is optional.
The 'Town' parameter is optional. * |
| SearchPremise_ByStreet_Dataset |
This search is the same as SearchThoroughfare_ByStreet but returns the data as a PostcodeUtilities dataset with a populated ListAddressPremise table. * |
A formal description of the services can be found in the 'Service Description' section of
http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above functions returns a collection of List Address Thoroughfares either as a dataset or List depending on the method invoked.
The ServiceTest function returns the status of the service and the number of credits currently available.
The List below describes the functions available:
| Function Name |
Function Description |
| ServiceTest |
This function takes 3 parameters and returns a string containing the status of the service and the number of credits currently available.
The 'AccountName' parameter must be entered.
The 'LicenceID' parameter must be entered.
Leave 'MachineID' blank. |
A formal description of the services can be found in the 'Service Description' section of
http://ws.epostcode.com/uk/postcodeservices.asmx
The response to a call of the above function returns a string value.