autocomplete/retrieve
Postcoder address autocomplete for the UK and Ireland provides real-time suggestions as a user types in their address. It consists of two types of request: one or more find requests to narrow down a list of address suggestions, and a retrieve request to retrieve a full address.
This is the retrieve endpoint and it returns the full address for a given suggestion ID. Before using this endpoint, use the autocomplete/find endpoint to get address suggestions and their IDs.
Request URL
GET https://ws.postcoder.com/pcw/autocomplete/retrieve/?id={suggestionid}&query={query}&country={countrycode}&apikey={apikey}
Querystring parameters
Parameter | Description | Example |
---|---|---|
id | The ID of the suggestion which was found using the /autocomplete/find endpoint | id=52752859 |
query | The URL-encoded search term which was used with /autocomplete/find endpoint | query=1%20birchwood |
countrycode | The 2-character country code, use uk for UK or ie for Ireland | country=uk |
apikey | Your API key | apikey=PCW45-12345-12345-1234X |
format | Sets the format of the response, xml or json (default unless "application/xml" header is detected) | format=json |
identifier | Specifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clients | identifier=websiteA |
lines | Sets the number of address lines (1-4) to include in the response so you can mirror the layout of your existing address form; use include and exclude below to further customise the address lines | lines=2 |
include | Specifies the extra address fields to include within the address lines using a comma-delimited list, supported values: county, posttown, postcode | include=county,posttown,postcode |
exclude | Specifies the address fields to exclude within the address lines using a comma-delimited list, supported values: pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | exclude=organisation |
addtags | Specifies the extra address fields to include within the response using a comma-delimited list, supported values: latitude, longitude, udprn, deliverypointsuffix, usercategory... see additional response fields below for the full list | addtags=latitude,longitude |
callback | Specifies the name of your JSONP callback function | callback=jsoncallback |
Example request and response
UK address lookup for a suggestion ID of "52752859" found using the autocomplete/find endpoint, with 2 address lines in the response
GET https://ws.postcoder.com/pcw/autocomplete/retrieve?id=52752859&query=1%20birchwood&country=uk&apikey=PCW45-12345-12345-1234X&format=json&lines=2
[
{
"addressline1": "Flat 1, Birchwood Apartments",
"addressline2": "Woodberry Grove",
"summaryline": "Flat 1, Birchwood Apartments, Woodberry Grove, London, Greater London, N4 1FR",
"subbuildingname": "Flat 1",
"buildingname": "Birchwood Apartments",
"premise": "Flat 1, Birchwood Apartments",
"street": "Woodberry Grove",
"posttown": "London",
"county": "Greater London",
"postcode": "N4 1FR"
}
]
Response fields
Field | Description | Example |
---|---|---|
summaryline | A summary of the address, ideal for displaying in a drop-down list | Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ |
addressline1 | The first line of the address, where the total number of address lines is defined by the lines querystring parameter | Manor Farm Barns |
addressline2 | The second line of the address | Fox Road |
addressline3 | The third line of the address | Framingham Pigot |
addressline4 | The fourth line of the address | Allies Computing Ltd |
pobox | The PO Box number | |
organisation | The organisation name at that address | Allies Computing Ltd |
departmentname | The department name | |
buildingname | The building name | Manor Farm Barns |
subbuildingname | The sub-building name | |
number | The house or flat number | 8 |
premise | The premise, a combination of buildingname, subbuildingname and number | Manor Farm Barns |
dependentstreet | The dependent street | |
street | The street | Fox Road |
doubledependentlocality | The double dependent locality | Eagle Road Industrial Estate |
dependentlocality | The dependent locality | Framingham Pigot |
posttown | The post town | Norwich |
county | The county | Norfolk |
postcode | The postcode | NR14 7PZ |
notyetbuilt | A true or false indicating whether the address is from the Royal Mail Not Yet Built dataset | true |
alias | A true or false indicating whether the address is a Royal Mail Alias record | true |
recodes | A colon-separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format) | CM7 8PX:1A:200112 |
Additional response fields
These additional fields can be included in the response by using the addtags
querystring parameter to specify a comma-delimited list of field names.
Example: addtags=latitude,longitude,udprn,deliverypointsuffix,usercategory
Field | Description | Querystring parameter to use |
---|---|---|
Coordinate data | ||
latitude | Latitude (ETRS89) | addtags=latitude |
longitude | Longitude (ETRS89) | addtags=longitude |
latitudeosgb | Latitude (OSGB36) | addtags=latitudeosgb36 |
longitudeosgb | Longitude (OSGB36) | addtags=longitudeosgb36 |
grideasting | Easting OS Grid Reference (1m precision in units of 1m) | addtags=grideast1metre |
gridnorthing | Northing OS Grid Reference (1m precision in units of 1m) | addtags=gridnorth1metre |
Address fields | ||
deliverypointsuffix | Delivery Point Suffix | addtags=deliverypointsuffix |
uniquedeliverypointreferencenumber | Unique Delivery Point Reference Number (UDPRN) | addtags=udprn |
multipleoccupancycount | Multiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery point | addtags=multipleoccupancycount |
administrativecounty | Administrative County (top tier local government) | addtags=administrativecounty |
postalcounty | Former Postal County | addtags=postalcounty |
traditionalcounty | Traditional County | addtags=traditionalcounty |
usercategory | User Category (residential 'R', Non-residential 'N', or Large 'L') | addtags=usercategory |
sortcode | Sortcode for Royal Mail Mailsort | addtags=sortcode |
countrycode | Country code (within the United Kingdom) | addtags=countrycode |
country | Country name (within the United Kingdom) | addtags=country |
welsh_dependentstreet | Welsh language alternative for dependent street field | addtags=welsh_dependentstreet |
welsh_street | Welsh language alternative for street field | addtags=welsh_street |
welsh_doubledependentlocality | Welsh language alternative for double dependent locality field | addtags=welsh_doubledependentlocality |
welsh_dependentlocality | Welsh language alternative for dependent locality field | addtags=welsh_dependentlocality |
welsh_posttown | Welsh language alternative for post town field | addtags=welsh_posttown |
Census data | ||
oa11 | 2011 Census Output Area | addtags=oa11 |
lsoa11 | 2011 Census Lower Layer Super Output Area | addtags=lsoa11 |
msoa11 | 2011 Census Middle Layer Super Output Area | addtags=msoa11 |
censusoutputarea_2001 | 2001 Census Output Area | addtags=censusoutputarea_2001 |
censuslowerlayersuperoutputarea_2001 | 2001 Census Lower Layer Super Output Area | addtags=censuslowerlayersuperoutputarea_2001 |
censusmiddlelayersuperoutputarea_2001 | 2001 Census Middle Layer Super Output Area | addtags=censusmiddlelayersuperoutputarea_2001 |
censusareastatisticswardcode | 2001 Census Area Statistics (CAS) Ward | addtags=censusareastatisticswardcode |
statisticalwardcode_2005 | 2005 Statistical Ward | addtags=statisticalwardcode_2005 |
NHS data | ||
commissioningregioncode_gss | NHS Commissioning Region Code (ONS GSS) | addtags=commissioningregioncode_gss |
commissioningregionname | NHS Commissioning Region Name | addtags=commissioningregionname |
areateamcode_nhs | NHS Area Team Code (NHS) | addtags=areateamcode_nhs |
areateamcode_gss | NHS Area Team Code (ONS GSS) | addtags=areateamcode_gss |
areateamname | NHS Area Team Name | addtags=areateamname |
clinicalcommissioninggroupcode_nhs | NHS Clinical Commissioning Group Code (NHS) | addtags=clinicalcommissioninggroupcode_nhs |
clinicalcommissioninggroupcode_gss | NHS Clinical Commissioning Group Code (ONS GSS) | addtags=clinicalcommissioninggroupcode_gss |
clinicalcommissioninggroupname | NHS Clinical Commissioning Group Name | addtags=clinicalcommissioninggroupname |
Government data | ||
localauthoritywardcode | Local Authority Ward Code | addtags=localauthoritywardcode |
localauthoritycode | Local Authority Code | addtags=localauthoritycode |
localauthorityname | Local Authority Name | addtags=localauthorityname |
electoralwardcode | Electoral Ward Code | addtags=electoralwardcode |
electoralwardname | Electoral Ward Name | addtags=electoralwardname |
electoralcountycode | Electoral County Code | addtags=electoralcountycode |
electoralcountyname | Electoral County Name | addtags=electoralcountyname |
parishcode | Parish Code | addtags=parishcode |
parliamentaryconstituencycode | Westminster Parliamentary Constituency Code | addtags=parliamentaryconstituencycode |
parliamentaryconstituencyname | Westminster Parliamentary Constituency Name | addtags=parliamentaryconstituencyname |
europeanelectoralregioncode | European Electoral Region Code | addtags=europeanelectoralregioncode |
europeanelectoralregionname | European Electoral Region Name | addtags=europeanelectoralregionname |
nationalparkname | National Park Name | addtags=nationalparkname |
nationalparkcode | National Park Code | addtags=nationalparkcode |
Integration advice
- URL encode all special characters (including /) in your request parameters with %xx encoding
- When using your API key across multiple websites, apps or clients, set the
identifier
querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page - Treat all response fields as optional
- Use these fields to create postal addresses:
- UK: addressline1, addressline2, posttown, postcode
- Ireland: addressline1, addressline2, posttown, county, postcode, country
Credit cost
Each request costs the following number of credits:
Country | Standard request | Enhanced request using addtags |
---|---|---|
UK | 2 credits | 2.4 credits |
Ireland | 4.5 credits | 4.5 credits |
Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.