Specification for Address UK Service

Check out the specification below to see how easy it is to integrate Address into your solutions.

Specification

Each request to a feedzon web service requires a number of parameters, all listed below. All requests require an API key which was generated when you activated an API key for that service. You can create multiple API keys for each service, if required.

feedzon method names and parameters names are all case sensitive, e.g. getKeyList will work but GetKeyList will not; Key=abc123 will work and KEY=abc123 will not. Data values are not case sensitive, so if you're searching a postcode WD18 6UW, you could also enter wd18 6uw.

 

URL Encoding

It is not necessary to URL encode any data.

Get Key List

Get a list of activated API keys for the Address service. If you have multiple API Keys set up for the Address service, e.g. one for internal use and one for external use, this function enables you to download the API Keys so you can choose which one to use. However if you only have a single Address API Key configured in your account for the Address service, then there is no need to use this function. If you need to use this function and don't have your unique 32 character account key (not to be confused with API keys), please log onto your feedzon account to retrieve it.

Request Format

https://api.feedzon.com/address/v1/getKeyList.fz?{parameters}

Example

https://api.feedzon.com/address/v1/getKeyList.fz?key=74hetRFD52FdgthsPlwst5weEErdD562

Results

"0"
"1b6e9c89053a651b68eb41d0e8c6c692","Office use"
"je9tEg5241LeS64sSh7532C6GghrEx78","Website use"
"hf6YTF985rF62VvhaoPor7623bfB762", "Website store locator"

Explanation of Results

Results are returned as quoted comma separated values. The first line of the result will be "0" for a successful result, or an error code. If the result is successful subsequent lines will have the API key for each enabled Address service along with the name for the service - you will need the appropriate API key for to use the service. If you didn't rename the service it might just show the default name 'My Application'.

Required Parameters

Name Type Description Example
key String Your unique 32 character account key 74hetRFD52FdgthsPlwst5weEErdD562

Get Address

Lookup an address. You can specify an organisation name, a street, town and/or a full or partial postcode. Use the general 'search' option to match your search criteria to any value in the address data or alternatively search a specific field, e.g. the street. A general search for 'Apple' will include organisations and streets with the word in them whereas a search for 'Apple' in the street name field will only find the appropriate matches. Uses 1 or 2 credits (for a street level or full address lookup respectively).

Request Format

https://api.feedzon.com/address/v1/getAddress.fz?{parameters}

Example A - Full Address Accuracy

https://api.feedzon.com/address/v1/getAddress.fz?key=1b6e9c89053a651b68eb41d0e8c6c692&lookup=FullAddress&search=Bacon Lane

Results A

"0"
"1", "100", "245"
"Bacon & Co", "50-52", "Crabtree Lane", "", "", "", "Lancing", "BN15 9PJ", "United Kingdom"
"Shake Ya Bacon", "71 Mill Lane", "", "", "", "", "Wallasey", "CH44 5UB", "United Kingdom"
"Lye Vale Bacon Ltd", "Peartree Lane", "", "", "", "", "Dudley", "DY2 0RS", "United Kingdom"
"British Bacon Supplies", "20 Barnet Lane", "", "", "", "", "Barnet", "EN5 2DN", "United Kingdom"
etc.

Explanation of Results A

Results are returned as quoted comma separated values. A search for 'Bacon Lane' with the 'FullAddress' parameter finds 245 matching results (one per individual property).

The first line of the result will be "0" for a successful result, or an error code. If the result is successful, the second line will detail the records being viewed and the total number of records found. Results are limited to 100 at a time for address searches and 1000 at a time for radius searches. If you perform an address search and 245 addresses match your search criteria, then the second line will look like this: "1","100","245". This means you're looking at results 1 to 100 of 245. Use the Page Number parameter to retrieve additional results. Requesting additional pages does not use additional credits as long as the search query remains unchanged and is performed within 10 minutes of the original query.

Results are returned as follows (some values may not be shown depending on the parameters used):

"Organisation", "Address 1", "Address 2", "Address 3", "Address 4", "Address 5", "Town", "Postcode", "Country", "Latitude", "Longitude", "Easting", "Northing", "Unique ID"

Example B - Street Address Accuracy

https://api.feedzon.com/address/v1/getAddress.fz?key=1b6e9c89053a651b68eb41d0e8c6c692&lookup=StreetAddress&search=Bacon Lane

Results B

"0"
"1", "22", "22"
"", "Bacon Lane", "Churt", "", "", "", "Farnham", "GU10 2QB", "United Kingdom"
"", "Bacon Lane", "Churt", "", "", "", "Farnham", "GU10 2QD", "United Kingdom"
"", "Bacon Lane", "Churt", "", "", "", "Farnham", "GU10 2QE", "United Kingdom"
"", "Bacon Lane", "", "", "", "", "Edgware", "HA8 5AP", "United Kingdom"
"", "Bacon Lane", "", "", "", "", "Edgware", "HA8 5AR", "United Kingdom"
etc.

Explanation of Results B

Results are returned as quoted comma separated values. A search for 'Bacon Lane' with the 'StreetAddress' parameter finds only 22 matching results (one per postcode). With the StreetAddress parameter, you may have to guess which is the correct postcode.

The results format is identical to the 'FullAddress' search above, except that the 'organisation' field will always be empty because organisation names are only available with the FullAddress option.

Required Parameters

Name Type Description Example
key String Your API key 1b6e9c89053a651b68eb41d0e8c6c692
lookup String Level of address accuracy. FullAddress is accurate to all 29 million properties in the UK and includes approximately 2 million business (organisation) names. StreetAddress is only accurate to street level and does not validate the door number matches the postcode.

A FullAddress lookup uses 2 credits.
A StreetAddress lookup uses 1 credit.
FullAddress
search String The address value(s) you want to search. Note that you can use the 'organisation', 'street', 'town' and/or 'postcode' parameters instead of 'search' if you want to only search on that specific field. 'Search' looks for matching values in any field of the address. If you specify a 'search' value and also specify one or more of the specific fields, the specific values will be ignored. Bacon Lane

Optional Parameters

Name Type Description Example
organisation String One or more full words from a business name. Optionally use with one or more of the other specific fields, e.g. a partial or full postcode, to help narrow down the results.

Only search organisation when using the parameter 'lookup=FullAddress', since organisation data is not licensed for use with the 'StreetAddress' level of accuracy.
Trade Mark Consultants
street String One or more full words from the street name.
Do not use abbreviations.
Wendover Way
town String One or more full words from the town name.
Do not use abbreviations.
Bushey
postcode String Any part of the postcode (we recommend a minimum of two characters of the postcode), with or without the space, e.g. for WD18 6UW, you could search for WD, WD1, WD18, WD18 6, WD18 6U or WD18 6UW. WD18 6UW
filter String Either 'OnlyResidential' or 'OnlyCommercial'. Causes only residential or commercial addresses to be returned.

This filter only works when using the 'FullAddress' level of accuracy since the residential or commercial data is not licensed for use with the 'StreetAddress' level of accuracy

Default value if not specified: No filter is applied; all addresses are returned.
Residential
geocode String Either 'True' or 'False' Causes the geocodes (geographical coordinates) to be returned with each address. Geocodes are returned in the following order: Latitude, Longitude, Easting, Northing.

Default value if not specified: False
True
record String Either 'True' or 'False' Causes a unique ID number to be returned as the last value with each address.

Default value if not specified: False
True
page_size Numeric Defines the maximum number of results to be returned per 'page' (see notes below).

Default value if not specified: 100
Maximum value: 100
100
page_number Numeric Defines the page number of results to be returned (see notes below).

Default value if not specified: 1

Error 1030: Note that if you request a Page Number higher than exists you will get an error 1030 on the first line, e.g. if you request Page Number 5 for a query that only has 4 pages of results data.
1

Page Size and Page Number Explained

If an address query finds 315 matching addresses, the first 100 will be returned on page 1, addresses 101 - 200 on page 2, addresses 201 - 300 on page 3 and addresses 301 - 315 on page 4. More accurate search queries will likely result in fewer matches and therefore it will be less likely that you'll need to page through the results.

Requesting additional pages does not use additional credits as long as the search query remains unchanged and is performed within 10 minutes of the original query.

To request the second or subsequent pages, change the page_number value. Any combination of page_size and page_number values can be used to return up to 1,000 results for a single address search (or up to 10,000 results for a single radius search).

Get Geocode

Geocode is short for 'geographical co-ordinates' and includes the latitude, longitude, easting & northing data for a given postcode. Uses 1 credit. Note that the GetAddress function above includes the geocode data if you specify the parameter 'geocode=True', so if you're performing an address lookup and need the geocode data as well, we recommend that method to get the address and geocode data all together. Only use this function if you want to append geocode data to your existing data and don't need to do a full address lookup.

Request Format

https://api.feedzon.com/address/v1/getGeocode.fz?{parameters}

Example

https://api.feedzon.com/address/v1/getGeocode.fz?key=74hetRFD52FdgthsPlwst5weEErdD562&postcode=WD24 4YY

Results

"0"
"51.642228567537", "-0.41940378750099", "509358", "194949"

Explanation of Results

Results are returned as quoted comma separated values. The first line of the result will be "0" for a successful result, or an error code. If the result is successful the second line will show the latitude, longitude, easting & northing values. Easting and northing are six-digit values provided by Royal Mail and Ordnance Survey and are accurate to approximately 10 metres.

Required Parameters

Name Type Description Example
key String Your API key 1b6e9c89053a651b68eb41d0e8c6c692
postcode String A full postcode is required, with or without the space. WD18 6UW

Distance Calculation

Calculate the distance between two postcodes. Uses 1 credit. All distances are calculated 'as the crow flies', e.g. a direct line. With distance values you can add extra features to your solution like:

Request Format

https://api.feedzon.com/address/v1/getDistance.fz?{parameters}

Example

https://api.feedzon.com/address/v1/getDistance.fz?key=1b6e9c89053a651b68eb41d0e8c6c692&postcode_a=WD24 4YY&postcode_b=WD18 6UW&unit=Mi

Results

"0"
"2.15"

Explanation of Results

Results are returned as quoted comma separated values. The first line of the result will be "0" for a successful result, or an error code. If the result is successful the second line will show the distance between the two postcodes in the unit specified.

Required Parameters

Name Type Description Example
key String Your API key 1b6e9c89053a651b68eb41d0e8c6c692
postcode_a String The starting postcode.
A full postcode is required, with or without the space.
WD24 4YY
postcode_b String The ending postcode.
A full postcode is required, with or without the space.
WD18 6UW
unit String Specify whether you want the result returned in
Km (kilometres) or Mi (miles).
Mi

Radius Search

Find all postcodes within a radius of a postcode. Uses 1 credit. With this feature you could identify clients within a radius of a sales representative. If you were running a promotion at a venue, you could identify all your customers within a given radius of that venue and invite them along. We're actually interested to hear how you use this feature, so please let us know!

Request Format

https://api.feedzon.com/address/v1/findByRadius.fz?{parameters}

Example

https://api.feedzon.com/address/v1/findByRadius.fz?key=74hetRFD52FdgthsPlwst5weEErdD562&postcode=WD18 6UW&radius=3.55&unit=Km

Results (with include_distance parameter set to 'false' or unspecified)

"0"
"1", "1000", "2950"
"WD18 6UW"
"WD18 6UQ"
"WD18 6UT"
"WD18 6UR"
etc.

Results (with include_distance parameter set to 'true')

"0"
"1", "1000", "2950"
"WD18 6UW", "0.00"
"WD18 6UQ", "0.05"
"WD18 6UT", "0.05"
"WD18 6UR", "0.06"
etc.

Explanation of Results

Results are returned as quoted comma separated values. A radius search for WD18 6UW with a radius of 3.55Km finds 2,950 matches (one per postcode).

The first line of the result will be "0" for a successful result, or an error code. If the result is successful, the second line will detail the records being viewed and the total number of records found. Results are limited to 1000 at a time for radius searches. If you perform a radius search and 2,950 postcodes match, then the second line will look like this: "1","1000","2950". This means you're looking at results 1 to 1,000 of 2,950. Use the Page Number parameter to retrieve additional results. Requesting additional pages does not use additional credits as long as the search query remains unchanged and is performed within 10 minutes of the original query.

How to use these results in FileMaker

FileMaker has a great feature whereby you can have a multi-value return separated key on the left side of a relationship and when you use the 'Go to Related Record' script step (GTRR), it find all related records for every value in the list. In this case the left-side of the relationship is a field with a list of return separated postcodes and the field on the right side of the relationship is the postcode field in your address table, so the GTRR will find all matching customer records in the specified radius.

Note that you'll need to remove the quotation marks which can be done using the substitute command and the list should not include the distances. We presume that your address table has postcodes entered with a space in the middle, but if that's not always the case, you can append to your left-side list a copy of the list with the space removed, again using the substitute command. FileMaker's GTRR script step is not case sensitive, so WD18 6UW on the left will match to Wd18 6uW on the right, for example, but if your postcode data entry has been less than perfect and 0's have been exchanged with O's and 1's exchanged with l's, for example, then you need to clean up your data - for which we recommend the GetAddress function above :)

Required Parameters

Name Type Description Example
key String Your API key 1b6e9c89053a651b68eb41d0e8c6c692
postcode String A full postcode is required, with or without the space. WD18 6UW
radius Numeric A value specifying the precise distance you want to search, accurate to two decimal places.

Maximum value: 100, which will result in a maximum of 10,000 postcodes being returned.
3.55
unit String Specify whether the radius value is in
Km (kilometres) or Mi (miles).
Km

Optional Parameters

Name Type Description Example
include_distance String Either 'True' or 'False'. Causes the distance value to be returned along with each postcode. True
page_size Numeric Defines the maximum number of results to be returned per 'page' (see notes below).

Default value if not specified: 1000
Maximum value: 1000
1000
page_number Numeric Defines the page number of results to be returned (see notes below).

Default value if not specified: 1

Error 1030: Note that if you request a Page Number higher than exists you will get an error 1030 on the first line, e.g. if you request Page Number 5 for a query that only has 4 pages of results data.
1

Page Size and Page Number Explained

If a radius query finds 2,950 matching postcodes, the first 1,000 will be returned on page 1, postcodes 1001 - 2,000 on page 2 and postcodes 2,001 - 2,950 on page 3.

Requesting additional pages does not use additional credits as long as the search query remains unchanged and is performed within 10 minutes of the original query.

To request the second or subsequent pages, change the page_number value. Any combination of page_size and page_number values can be used to return up to 10,000 results for a single radius search.

Response Errors

No credits are used in the event of an error being returned.

Error Description Cause Resolution
-1 Function doesn't exist The function name doesn't exist or has been spelled incorrectly. Please check your syntax for any errors since all function names and parameter names are case sensitive.
1000 Service Key is invalid The Service Key used to access feedzon was not recognised or has been disabled.

This error code will also display if you have not selected 'Interal', 'External' or 'Store Locator' in the address service.
Please check your Service Key, re-enable the service (if it's disabled) and check all options have been set correctly in the address service. Please contact us if you've checked all the above and are still receiving this error code.
1010 Missing parameters One or more parameters are missing Please check the parameters section to identify which parameters are required for the specified command.
1020 Validation error One or more of the data values was not recognised, e.g. the postcode is invalid. Please check the data values.
1030 Page number error The requested page number does not exist. You requested a Page Number higher than exists, e.g. you requested Page Number 5 for a query that only has 4 pages of results data. Adjust the page number.
2000 Account credit error Your feedzon account is out of credit or does not have sufficient credits remaining for the requested service. Please login to your feedzon account and purchase additional credits. For the feedzon Address service please ensure to purchase the correct pack of credits, e.g. External (website) or Internal (office, intranet) use. Also consider adding an auto top-up to avoid this problem in the future.