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.

Ireland and Eircode: Enable access on your API key using the Data Options page or by contacting us.

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

After finding suggestions using the autocomplete/find endpoint, return the UK address with a suggestion ID of 52752859 and include two 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, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE
`addressline1`	The first line of the address, where the total number of address lines is defined by the `lines` querystring parameter	Allies Computing Ltd
`addressline2`	The second line of the address	92 St. Faiths Lane
`addressline3`	The third line of the address
`addressline4`	The fourth line of the address
`pobox`	The PO Box number
`organisation`	The organisation name at that address	Allies Computing Ltd
`departmentname`	The department name
`buildingname`	The building name
`subbuildingname`	The sub-building name
`number`	The house or flat number	92
`premise`	The premise, a combination of buildingname, subbuildingname and number	92
`dependentstreet`	The dependent street
`street`	The street	St. Faiths Lane
`doubledependentlocality`	The double dependent locality
`dependentlocality`	The dependent locality
`posttown`	The post town	Norwich
`county`	The county	Norfolk
`postcode`	The postcode	NR1 1NE
`notyetbuilt`	A true or false indicating whether the address is from the Royal Mail Not Yet Built dataset	false
`alias`	A true or false indicating whether the address is a Royal Mail Alias record	false
`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.