address

Request URL

GET https://ws.postcoder.com/pcw/{apikey}/address/{countrycode}/{searchterm}

Path parameters

Querystring parameters

Supported countries and country codes

The following countries are supported by this endpoint. The address and geocoding levels shown for each country reflect the highest level of data supported. There are three levels:

• Premise: delivery points and buildings
• Street: streets and similar levels of geography
• Locality: villages, towns and cities

Example requests and responses

Return UK addresses with a postcode of NR1 1NE and include up to 3 address lines in the response:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/uk/nr1%201ne?format=json&lines=3

[
	...
	...
	{
		"addressline1": "Allies Computing Ltd",
		"addressline2": "92 St. Faiths Lane",
		"summaryline": "Allies Computing Ltd, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE",
		"organisation": "Allies Computing Ltd",
		"number": "92",
		"premise": "92",
		"street": "St. Faiths Lane",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR1 1NE"
	},
	...
	...
]

Return US addresses that match "1600 Pennsylvania, 20500-0001" and include up to 3 address lines (which exclude the organisation and country fields) in the response:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/us/1600%20pennsylvania,%2020500-0001?format=json&lines=3&exclude=organisation,country

[
	{
		"addressline1": "1600 PENNSYLVANIA AVE NW",
		"addressline2": "WASHINGTON DC  20500-0001",
		"summaryline": "1600 PENNSYLVANIA AVE NW, WASHINGTON DC  20500-0001",
		"organisation": "PRESIDENT",
		"number": "1600",
		"premise": "1600",
		"street": "PENNSYLVANIA AVE NW",
		"posttown": "WASHINGTON",
		"county": "DISTRICT OF COLUMBIA",
		"state": "DISTRICT OF COLUMBIA",
		"stateabbreviation": "DC",
		"postcode": "20500-0001",
		"country": "UNITED STATES"
	}
]

Return the Irish address with an Eircode of D02X285 and include up to 3 address lines and coordinates in the response:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/ie/d02x285?format=json&lines=3&addtags=latitude,longitude

[
	{
		"addressline1": "Department of Communications, Climate Action and Environment",
		"addressline2": "29-31 Adelaide Road",
		"summaryline": "Department of Communications, Climate Action and Environment, 29-31 Adelaide Road, Dublin 2, D02 X285",
		"organisation": "Department of Communications, Climate Action and Environment",
		"number": "29-31",
		"premise": "29-31",
		"street": "Adelaide Road",
		"posttown": "Dublin 2",
		"county": "Co. Dublin",
		"postcode": "D02 X285",
		"latitude": "53.332067",
		"longitude": "-6.255492"
	}
]

Response fields

Additional response fields

Use the addtags querystring parameter to specify a comma-delimited list of fields that you wish to add to the response. For example, to add latitude, longitude and udprn:

GET https://ws.postcoder.com/pcw/...?format=json&lines=2&addtags=latitude,longitude,udprn

Address lines

When returning addresses using this endpoint, Postcoder can optionally return up to 9 address lines that contain all the address elements (such as organisation, number, street, dependentlocality, posttown, county, postcode and country) needed to represent each address.

	"addressline1":"123 Rue Brizeux",
	"addressline2":"29860 Plouvien",
	...

The address lines returned by Postcoder for addresses in the UK (country=uk), Guernsey (gg), Jersey (je), Isle of Man (im) and Ireland (ie) are different: they do not contain the posttown, county, postcode and country by default.

	"addressline1": "123 Foxglove Lane",
	"addressline2": "Biddenham",
	...

You can specify the number of address lines by setting the lines querystring parameter in your request to 1, 2, 3... or 9. To return up to 3 address lines, for example:

GET https://ws.postcoder.com/pcw/{apikey}/address/{countrycode}/{searchterm}?format=json&lines=3

You can customise what is contained within the address lines by setting the include and exclude querystring parameters. For example, to exclude the posttown, county, postcode and country when retrieving a French address:

GET https://ws.postcoder.com/pcw/{apikey}/address/fr/{searchterm}?format=json&lines=3&exclude=posttown,county,postcode,country

	"addressline1":"123 Rue Brizeux",
	...

You can use the address lines and address elements returned by Postcoder to populate any type of address form. If your users or customers are worldwide, your address form may contain these fields:

When the country is UK (country=uk), Guernsey (gg), Jersey (je), Isle of Man (im) or Ireland (ie), this request structure will return the response fields you need:

GET https://ws.postcoder.com/pcw/{apikey}/address/{countrycode}/{searchterm}?format=json&lines=3

	"addressline1": "123 Foxglove Lane",
	"addressline2": "Biddenham",
	...
	"posttown": "Ashford",
	"county": "Kent",
	"postcode": "TN27 8BT"

For any other country, this request structure will return the response fields you need:

GET https://ws.postcoder.com/pcw/{apikey}/address/{countrycode}/{searchterm}?format=json&lines=3&exclude=posttown,county,postcode,country

	"addressline1":"123 Rue Brizeux",
	...
	"posttown": "Plouvien",
	"county": "Finistère",
	"postcode": "29860",

Integration advice

• URL encode all special characters (including /) in your request parameters with %xx encoding
• Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
• 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
• County is no longer required in UK addresses; however, it may include essential postal details for addresses in other countries

Credit cost

Each request costs the following number of credits:

Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.