Address lookup API
Postcoder provides the fastest, most reliable way to capture accurate addresses.
Postcode to address lookup
Lookup UK addresses using postcodes, and Irish addresses using Eircodes.
Uses the latest PAF and Multiple Residence data from Royal Mail, and ECAD data from Eircode.
Example code
Node JS Example PHP Example Javascript Example React Example jQuery Example iOS Swift Example C# Example
Request URL
UK postcode lookup
GET | https://ws.postcoder.com/pcw/[apikey]/address/uk/[postcode-or-address-fragment]
Irish Eircode lookup
GET | https://ws.postcoder.com/pcw/[apikey]/address/ie/[eircode-or-address-fragment]
Try it now
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| lines | Sets the number of address lines over which to display the first part of each address in the response | 0, 1, 2, 3, 4 | 0 |
| include | Specifies the extra address fields to include within the address lines, using a comma-delimited list | county, posttown, postcode | |
| exclude | Specifies the address fields to exclude within the address lines, using a comma-delimited list | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | |
| addtags | Specifies the extra address fields to include within the response, using a comma-delimited list | See Additional data fields | |
| postcodeonly | Limits the request to a postcode-only search rather than matching the search term on other parts of an address | true, false | false |
| alias | Includes aliases for addresses known to and accepted by Royal Mail | true, false | false |
| callback | Sets the name of your JSONP callback function | ||
| page | Specifies the page of results to return where 0 is the first page | 0, 1, 2, 3... | 0 |
Tip
- Be sure to URI encode the search term with percent encoding before sending your request to Postcoder. For example,
NR14 7PZshould becomeNR14%207PZ
Response fields for postal addresses
We recommend you use the following fields for a UK or Irish postal address:
| UK | Ireland |
|---|---|
| addressline1 | addressline1 |
| addressline2 | addressline2 |
| posttown | posttown |
| postcode | county |
| postcode |
Response fields
| Field | Description | Example | Returned by default? |
|---|---|---|---|
| summaryline | A string containing the entire address | Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ | Yes |
addressline[n] | Contains the [n]th line of the address for printing on a label. Won't contain posttown, postcode, or any fields excluded with ?exclude= | Allies Computing Ltd | Use ?lines=[n] to set number of required address lines |
| pobox | PO Box number, if present | Yes | |
| organisation | Organisation name at that address, if present | Allies Computing Ltd | Yes |
| departmentname | Department name | Yes | |
| buildingname | Building name | Manor Farm Barns | Yes |
| subbuildingname | Sub-building name | Yes | |
| number | House/Flat number | 8 | Yes |
| premise | Name of the premise | Manor Farm Barns | Yes |
| dependentstreet | Name of a dependent street if it is present in the address | Yes | |
| street | Street name | Fox Road | Yes |
| doubledependentlocality | Name of the double dependant locality, if it is present in the address | Eagle Road Industrial Estate | Yes |
| dependentlocality | Name of the dependent locality, if it is present in the address | Framingham Pigot | Yes |
| posttown | Posttown name. Always present in UK addresses | Norwich | Yes |
| county | County name | Norfolk | Yes |
| postcode | Postcode. Always present in UK addresses | NR14 7PZ | Yes |
| notyetbuilt | Boolean value that displays if an address is a part of the "Not Yet Built" dataset from Royal Mail | true | Use ?nyb=true |
| recodes | Colon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format) | CM7 8PX:1A:200112 | Yes |
| morevalues | Indicates at least one more page of addresses for the lookup | true | Yes |
| nextpage | Page number for the next page of results | 2 | Yes |
| totalresults | Total number of results for the lookup | 458 | Yes |
| longitude | The longitude associated with the result | 1.3491603533 | Use ?addtags=longitude |
| latitude | The latitude associated with the result | 52.5859730797 | Use ?addtags=latitude |
| uniquedeliverypointreferencenumber | Unique Delivery Point Reference Number (UDPRN) - a unique number applied by Royal Mail to every UK delivery point | 17448021 | Use ?addtags=udprn |
| alias | Indicates if an address is an alias record. | true | Use ?alias=true |
Predictive address autocomplete
Autocomplete UK addresses and Irish addresses with predictive as-you-type suggestions.
Uses the latest PAF and Multiple Residence data from Royal Mail, and ECAD data from Eircode.
Example code
Step 1: Request URL - Return as-you-type suggestions
GET | https://ws.postcoder.com/pcw/autocomplete/find
?query=[first-letters-of-address]
&country=[country]
&apikey=[apikey]
Step 1: Querystring parameters
| Parameter | Description | Required | Values |
|---|---|---|---|
| query | The search term (minimum of three characters required, returns empty array otherwise) | Yes | E.g. 1 birchwood h |
| pathfilter | Allows you to narrow down the search using the ID of a suggestion that was not an address from a previous request (i.e. where the type was not "ADD") | No | E.g. UK@STATE\|Suffolk@CTY\|{Rushmere St. Andrew@LOC,Ipswich@PTN,IP@PCDA}@LOC|{Birchwood Drive@STR,IP5-1EB@PCD}@PCD |
| country | The 2 letter ISO 3166-1 country code | Yes | UK or IE |
| apikey | The API key | Yes | E.g. PCW45-12345-12345-1234X |
| format | The response format; default is JSON unless an application/xml header is detected | No | json or xml |
| maximumresults | The maximum number of results to return; default is 30 | No | 5 - 30 |
| enablefacets | Groups some results together geographically when the search term is too vague to make a confident suggestion, making drilling down with ?pathfilter easier. Set to false to disable this behaviour. | No | false |
Tip
- If you're having issues with Chrome's autofill blocking your suggestions, use the
autocomplete="xyz"attribute in your input tag. Chrome ignores theautocomplete="off"attribute.
Step 1: Response fields
| Field | Description | Example | Returned by default? |
|---|---|---|---|
| id | The ID of the address or place | 52752859 | Yes |
| type | The type of suggestion; see definitions below | ADD | Yes |
| summaryline | The summary of the address or place | 1 Birchwood Hall Cottages | Yes |
| locationsummary | The location associated with the address or place | Chathill, Northumberland, NE67 5LG | Yes |
| count | The number of further suggestions nested within the suggestion | 66 | Yes |
Definitions for the 'type' response field
| Name | Description |
|---|---|
| ADD | Address |
| BGN | Building group |
| BNA | Building name |
| CCN | County |
| DST | Dependent street |
| LAD | District borough |
| LOC | Place |
| LOC2 | Dependent place |
| LOC3 | Double dependent place |
| NUM | Number |
| ORC | Organisation |
| ORD | Department |
| PCD | Postcode |
| PCDA | Postcode area |
| PCDD | Postcode district |
| PCDS | Postcode sector |
| PCDU1 | Postcode unit 1 |
| POB | PO Box |
| SBN | Sub building name |
| STATE | State |
| STR | Street |
| WORLD | World |
Step 2: Request URL - Return a full address
GET | https://ws.postcoder.com/pcw/autocomplete/retrieve
?id=[id-from-step-one]
&query=[query-from-step-one]
&country=[country]
&apikey=[apikey]
Step 2: Querystring parameters
| Parameter | Description | Required | Values |
|---|---|---|---|
| id | The ID of a suggestion that was an address from a previous request (i.e. where the type was 'ADD') | Yes | 6219058 |
| query | The original search term | Yes | E.g. 1 birchwood h |
| country | The 2 letter ISO 3166-1 country code | Yes | UK or IE |
| apikey | The API key | Yes | E.g. PCW45-12345-12345-1234X |
| format | The response format; default is JSON unless an application/xml header is detected | No | json or xml |
| identifier | Identify your lookup to make debugging and reviewing stats easier | No | E.g. myform |
| lines | The number of lines over which to split the address | No | 0, 1, 2, 3, 4 |
| include | Include extra address fields within the address lines returned | No | county, posttown, postcode |
| exclude | Exclude address fields within the address lines returned | No | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality |
| addtags | Add extra address fields such as UDPRN to the return | No | See Additional data fields |
| callback | Use to specify the name of your JSONP callback function | No |
Step 2: Response fields
| Field | Description | Example | Returned by default? |
|---|---|---|---|
| summaryline | A string containing the entire address | Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ | Yes |
addressline[n] | Contains the [n]th line of the address for printing on a label. Won't contain posttown, postcode, or any fields excluded with ?exclude= | Allies Computing Ltd | Use ?lines=[n] to set number of required address lines |
| pobox | PO Box number, if present | Yes | |
| organisation | Organisation name at that address, if present | Allies Computing Ltd | Yes |
| departmentname | Department name | Yes | |
| buildingname | Building name | Manor Farm Barns | Yes |
| subbuildingname | Sub-building name | Yes | |
| number | House/Flat number | 8 | Yes |
| premise | Name of the premise | Manor Farm Barns | Yes |
| dependentstreet | Name of a dependent street if it is present in the address | Yes | |
| street | Street name | Fox Road | Yes |
| doubledependentlocality | Name of the double dependant locality, if it is present in the address | Eagle Road Industrial Estate | Yes |
| dependentlocality | Name of the dependent locality, if it is present in the address | Framingham Pigot | Yes |
| posttown | Posttown name. Always present in UK addresses | Norwich | Yes |
| county | County name | Norfolk | Yes |
| postcode | Postcode. Always present in UK addresses | NR14 7PZ | Yes |
| notyetbuilt | Boolean value that displays if an address is a part of the "Not Yet Built" dataset from Royal Mail | true | Use ?nyb=true |
| recodes | Colon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format) | CM7 8PX:1A:200112 | Yes |
| morevalues | Indicates at least one more page of addresses for the lookup | true | Yes |
| nextpage | Page number for the next page of results | 2 | Yes |
| totalresults | Total number of results for the lookup | 458 | Yes |
| longitude | The longitude associated with the result | 1.3491603533 | Use ?addtags=longitude |
| latitude | The latitude associated with the result | 52.5859730797 | Use ?addtags=latitude |
| alias | Indicates if an address is an alias record. | true | Use ?alias=true |
Examples
Show suggestions for "1 birchwood h"
https://ws.postcoder.com/pcw/autocomplete/find
?query=1%20birchwood%20h
&country=UK
&apikey=PCW45-12345-12345-1234X
&format=json
[
{
"id": "16291869",
"type": "ADD",
"summaryline": "1 Birchwood Hall Cottages",
"locationsummary": "Chathill, Northumberland, NE67 5LG",
"count": 1
},
...
{
"id": "UK@STATE|Greater London@CTY|London@LOC|Hackney@LAD|{Woodberry Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood Apartments@BNA,Flat 1-66@RNG}@PCD",
"type": "PCD",
"summaryline": "Flat 1-66, Birchwood Apartments, N4 1FR",
"locationsummary": "Woodberry Grove, London, Hackney",
"count": 66
}
]Expand the "Flat 1-66, Birchwood Apartments, N4 1FR" suggestion found above
https://ws.postcoder.com/pcw/autocomplete/find
?query=1%20birchwood%20h
&pathfilter=UK@STATE|Greater%20London@CTY|London@LOC|Hackney@LAD|{Woodberry%20Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood%20Apartments@BNA,Flat%201-66@RNG}@PCD
&country=UK
&apikey=PCW45-12345-12345-1234X
&format=json
[
{
"id": "52752859",
"type": "ADD",
"summaryline": "Flat 1",
"locationsummary": "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
"count": 1
},
...
{
"id": "52752397",
"type": "ADD",
"summaryline": "Flat 64",
"locationsummary": "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
count: 1
}
]Retrieve full address for the "Flat 1, Birchwood Apartments" suggestion found above
https://ws.postcoder.com/pcw/autocomplete/retrieve
?id=52752859
&query=1%20birchwood%20h
&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"
}
]Additional data fields
Include additional fields by appending ?addtags=[comma-delimited-addtags-field-names] to your request URL.
Address data
| Description | Addtags field name | Tag name returned in output |
|---|---|---|
| Delivery Point Suffix | deliverypointsuffix | deliverypointsuffix |
| Unique Delivery Point Reference Number (UDPRN) | udprn | uniquedeliverypointreferencenumber |
| Multiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery point | multipleoccupancycount | multipleoccupancycount |
| Administrative County (top tier local government) | administrativecounty | administrativecounty |
| Former Postal County | postalcounty | postalcounty |
| Traditional County | traditionalcounty | traditionalcounty |
| User Category (residential 'R', Non-residential 'N', or Large 'L') | usercategory | usercategory |
| Sortcode (for Royal Mail Mailsort) | sortcode | sortcode |
| Country code (within the United Kingdom) | countrycode | countrycode |
| Country name (within the United Kingdom) | country | country |
| Welsh language alternative for dependent street field | welsh_dependentstreet | welsh_dependentstreet |
| Welsh language alternative for street field | welsh_street | welsh_street |
| Welsh language alternative for double dependent locality field | welsh_doubledependentlocality | welsh_doubledependentlocality |
| Welsh language alternative for dependent locality field | welsh_dependentlocality | welsh_dependentlocality |
| Welsh language alternative for post town field | welsh_posttown | welsh_posttown |
Coordinates
| Description | Addtags field name | Tag name returned in output |
|---|---|---|
| Easting OS Grid Reference (1m precision in units of 1m) | grideast1metre | grideasting |
| Northing OS Grid Reference (1m precision in units of 1m) | gridnorth1metre | gridnorthing |
| Latitude (OSGB36) | latitudeosgb36 | latitudeosgb |
| Longitude (OSGB36) | longitudeosgb36 | longitudeosgb |
| Latitude (ETRS89) | latitudeetrs89 | latitude |
| Longitude (ETRS89) | longitudeetrs89 | longitude |
Census data
| Description | Addtags field name | Tag name returned in output |
|---|---|---|
| 2011 Census Output Area | oa11 | oa11 |
| 2011 Census Lower Layer Super Output Area | lsoa11 | lsoa11 |
| 2011 Census Middle Layer Super Output Area | msoa11 | msoa11 |
| 2001 Census Output Area | censusoutputarea_2001 | censusoutputarea_2001 |
| 2001 Census Lower Layer Super Output Area | censuslowerlayersuperoutputarea_2001 | censuslowerlayersuperoutputarea_2001 |
| 2001 Census Middle Layer Super Output Area | censusmiddlelayersuperoutputarea_2001 | censusmiddlelayersuperoutputarea_2001 |
| 2001 Census Area Statistics (CAS) Ward | censusareastatisticswardcode | censusareastatisticswardcode |
| 2005 Statistical Ward | statisticalwardcode_2005 | statisticalwardcode_2005 |
NHS data
| Description | Addtags field name | Tag name returned in output |
|---|---|---|
| NHS Commissioning Region Code (ONS GSS) | commissioningregioncode_gss | commissioningregioncode_gss |
| NHS Commissioning Region Name | commissioningregionname | commissioningregionname |
| NHS Area Team Code (NHS) | areateamcode_nhs | areateamcode_nhs |
| NHS Area Team Code (ONS GSS) | areateamcode_gss | areateamcode_gss |
| NHS Area Team Name | areateamname | areateamname |
| NHS Clinical Commissioning Group Code (NHS) | clinicalcommissioninggroupcode_nhs | clinicalcommissioninggroupcode_nhs |
| NHS Clinical Commissioning Group Code (ONS GSS) | clinicalcommissioninggroupcode_gss | clinicalcommissioninggroupcode_gss |
| NHS Clinical Commissioning Group Name | clinicalcommissioninggroupname | clinicalcommissioninggroupname |
Government data
| Description | Addtags field name | Tag name returned in output |
|---|---|---|
| Local Authority Ward Code | localauthoritywardcode | localauthoritywardcode |
| Local Authority Code | localauthoritycode | localauthoritycode |
| Local Authority Name | localauthorityname | localauthorityname |
| Electoral Ward Code | electoralwardcode | electoralwardcode |
| Electoral Ward Name | electoralwardname | electoralwardname |
| Electoral County Code | electoralcountycode | electoralcountycode |
| Electoral County Name | electoralcountyname | electoralcountyname |
| Parish Code | parishcode | parishcode |
| Westminster Parliamentary Constituency Code | parliamentaryconstituencycode | parliamentaryconstituencycode |
| Westminster Parliamentary Constituency Name | parliamentaryconstituencyname | parliamentaryconstituencyname |
| European Electoral Region Code | europeanelectoralregioncode | europeanelectoralregioncode |
| European Electoral Region Name | europeanelectoralregionname | europeanelectoralregionname |
| National Park Name | nationalparkname | nationalparkname |
| National Park Code | nationalparkcode | nationalparkcode |
International address lookup
Lookup international addresses using the first address line and / or postal code.
Request URL
GET | https://ws.postcoder.com/pcw/[apikey]/address/[country-code]/[address-fragment]
Example
[
{
"addressline1": "PRESIDENT",
"addressline2": "1600 PENNSYLVANIA AVE NW",
"addressline3": "WASHINGTON DC 20500-0001",
"addressline4": "UNITED STATES",
"summaryline": "PRESIDENT, 1600 PENNSYLVANIA AVE NW, WASHINGTON DC 20500-0001, UNITED STATES",
"organisation": "PRESIDENT",
"number": "1600",
"premise": "1600",
"street": "PENNSYLVANIA AVE NW",
"posttown": "WASHINGTON",
"state": "DISTRICT OF COLUMBIA",
"stateabbreviation": "DC",
"postcode": "20500-0001",
"country": "UNITED STATES"
}
]Supported countries and country codes
| Code | Country | Buildings | Streets | Towns | Updated |
|---|---|---|---|---|---|
| AF | Afghanistan | ✔ | Quarterly | ||
| AL | Albania | ✔ | ✔ | Quarterly | |
| AQ | Antarctica | ✔ | Quarterly | ||
| DZ | Algeria | ✔ | ✔ | Quarterly | |
| AS | American Samoa | ✔ | ✔ | ✔ | Monthly |
| AD | Andorra | ✔ | ✔ | ✔ | Quarterly |
| AO | Angola | ✔ | ✔ | Quarterly | |
| AG | Antigua and Barbuda | ✔ | ✔ | Quarterly | |
| AZ | Azerbaijan | ✔ | ✔ | ✔ | Quarterly |
| AR | Argentina | ✔ | ✔ | ✔ | Quarterly |
| AU | Australia | ✔ | ✔ | ✔ | Quarterly |
| AT | Austria | ✔ | ✔ | ✔ | Monthly |
| BS | Bahamas | ✔ | ✔ | ✔ | Quarterly |
| BH | Bahrain | ✔ | ✔ | ✔ | Quarterly |
| BD | Bangladesh | ✔ | ✔ | Quarterly | |
| AM | Armenia | ✔ | ✔ | Quarterly | |
| BB | Barbados | ✔ | ✔ | Quarterly | |
| BE | Belgium | ✔ | ✔ | ✔ | Quarterly |
| BM | Bermuda | ✔ | ✔ | Quarterly | |
| BT | Bhutan | ✔ | ✔ | Quarterly | |
| BO | Bolivia | ✔ | ✔ | Quarterly | |
| BA | Bosnia and Herzegovina | ✔ | ✔ | ✔ | Quarterly |
| BW | Botswana | ✔ | ✔ | ✔ | Quarterly |
| BR | Brazil | ✔ | ✔ | ✔ | Quarterly |
| BZ | Belize | ✔ | ✔ | Quarterly | |
| IO | Br. Indian Ocean Ter. | ✔ | Quarterly | ||
| SB | Solomon Islands | ✔ | ✔ | Quarterly | |
| VG | Virgin Islands, British | ✔ | ✔ | Quarterly | |
| BN | Brunei Darussalam | ✔ | ✔ | ✔ | Quarterly |
| BG | Bulgaria | ✔ | ✔ | ✔ | Quarterly |
| MM | Myanmar | ✔ | ✔ | Quarterly | |
| BI | Burundi | ✔ | ✔ | Quarterly | |
| BY | Belarus | ✔ | ✔ | Quarterly | |
| KH | Cambodia | ✔ | ✔ | Quarterly | |
| CM | Cameroon | ✔ | ✔ | Quarterly | |
| CA | Canada | ✔ | ✔ | ✔ | Quarterly |
| CV | Cape Verde | ✔ | ✔ | Quarterly | |
| KY | Cayman Islands | ✔ | ✔ | ✔ | Quarterly |
| CF | Central African Rep. | ✔ | ✔ | Quarterly | |
| LK | Sri Lanka | ✔ | ✔ | Quarterly | |
| TD | Chad | ✔ | ✔ | Quarterly | |
| CL | Chile | ✔ | ✔ | ✔ | Quarterly |
| CN | China | ✔ | ✔ | Quarterly | |
| TW | Taiwan | ✔ | ✔ | ✔ | Quarterly |
| CX | Christmas Island | ✔ | Quarterly | ||
| CC | Cocos (Keeling) Islands | ✔ | Quarterly | ||
| CO | Colombia | ✔ | ✔ | ✔ | Quarterly |
| KM | Comoros | ✔ | ✔ | Quarterly | |
| YT | Mayotte | ✔ | ✔ | Quarterly | |
| CG | Congo (Rep.) | ✔ | ✔ | Quarterly | |
| CD | Congo (Dem. Rep.) | ✔ | ✔ | Quarterly | |
| CK | Cook Islands | ✔ | ✔ | Quarterly | |
| CR | Costa Rica | ✔ | ✔ | ✔ | Quarterly |
| HR | Croatia | ✔ | ✔ | ✔ | Quarterly |
| CU | Cuba | ✔ | ✔ | Quarterly | |
| CY | Cyprus | ✔ | ✔ | ✔ | Quarterly |
| CZ | Czech Republic | ✔ | ✔ | ✔ | Quarterly |
| BJ | Benin | ✔ | ✔ | Quarterly | |
| DK | Denmark | ✔ | ✔ | ✔ | Quarterly |
| DM | Dominica | ✔ | ✔ | Quarterly | |
| DO | Dominican Republic | ✔ | ✔ | Quarterly | |
| EC | Ecuador | ✔ | ✔ | ✔ | Quarterly |
| SV | El Salvador | ✔ | ✔ | Quarterly | |
| GQ | Equatorial Guinea | ✔ | ✔ | Quarterly | |
| ET | Ethiopia | ✔ | ✔ | Quarterly | |
| ER | Eritrea | ✔ | ✔ | Quarterly | |
| EE | Estonia | ✔ | ✔ | ✔ | Quarterly |
| FO | Faröe Islands | ✔ | ✔ | Quarterly | |
| FK | Falkland Is. (Malvinas) | ✔ | ✔ | Quarterly | |
| GS | S. Georgia and S. Sandwich | ✔ | Quarterly | ||
| FJ | Fiji | ✔ | ✔ | Quarterly | |
| FI | Finland | ✔ | ✔ | ✔ | Quarterly |
| AX | Aland Islands | ✔ | ✔ | ✔ | Quarterly |
| FR | France | ✔ | ✔ | ✔ | Quarterly |
| GF | French Guiana | ✔ | ✔ | ✔ | Quarterly |
| PF | French Polynesia | ✔ | ✔ | Quarterly | |
| TF | French Southern Territories | ✔ | Quarterly | ||
| DJ | Djibouti | ✔ | ✔ | Quarterly | |
| GA | Gabon | ✔ | ✔ | Quarterly | |
| GE | Georgia | ✔ | ✔ | Quarterly | |
| GM | Gambia | ✔ | ✔ | Quarterly | |
| PS | Palestinian Territory | ✔ | Quarterly | ||
| DE | Germany | ✔ | ✔ | ✔ | Quarterly |
| GH | Ghana | ✔ | ✔ | Quarterly | |
| GI | Gibraltar | ✔ | ✔ | ✔ | Quarterly |
| KI | Kiribati | ✔ | ✔ | Quarterly | |
| GR | Greece | ✔ | ✔ | ✔ | Quarterly |
| GL | Greenland | ✔ | ✔ | Quarterly | |
| GD | Grenada | ✔ | ✔ | Quarterly | |
| GP | Guadeloupe | ✔ | ✔ | ✔ | Quarterly |
| GU | Guam | ✔ | ✔ | ✔ | Monthly |
| GT | Guatemala | ✔ | ✔ | Quarterly | |
| GN | Guinea | ✔ | ✔ | Quarterly | |
| GY | Guyana | ✔ | ✔ | Quarterly | |
| HT | Haiti | ✔ | ✔ | Quarterly | |
| VA | Vatican City | ✔ | ✔ | Quarterly | |
| HN | Honduras | ✔ | ✔ | Quarterly | |
| HK | Hong Kong | ✔ | ✔ | ✔ | Quarterly |
| HU | Hungary | ✔ | ✔ | ✔ | Quarterly |
| IS | Iceland | ✔ | ✔ | ✔ | Quarterly |
| IN | India | ✔ | ✔ | ✔ | Quarterly |
| ID | Indonesia | ✔ | ✔ | ✔ | Quarterly |
| IR | Iran | ✔ | Quarterly | ||
| IQ | Iraq | ✔ | ✔ | Quarterly | |
| IE | Ireland | ✔ | ✔ | ✔ | Quarterly |
| IL | Israel | ✔ | ✔ | ✔ | Quarterly |
| IT | Italy | ✔ | ✔ | ✔ | Quarterly |
| CI | Côte d'Ivoire | ✔ | Quarterly | ||
| JM | Jamaica | ✔ | ✔ | Quarterly | |
| JP | Japan | ✔ | ✔ | ✔ | Quarterly |
| KZ | Kazakhstan | ✔ | ✔ | ✔ | Quarterly |
| JO | Jordan | ✔ | ✔ | ✔ | Quarterly |
| KE | Kenya | ✔ | ✔ | Quarterly | |
| KP | Korea (Dem. Rep.) | ✔ | Quarterly | ||
| KR | Korea (Rep.) | ✔ | ✔ | ✔ | Quarterly |
| KW | Kuwait | ✔ | ✔ | ✔ | Quarterly |
| KG | Kyrgyzstan | ✔ | ✔ | Quarterly | |
| LA | Laos | ✔ | Quarterly | ||
| LB | Lebanon | ✔ | ✔ | ✔ | Quarterly |
| LS | Lesotho | ✔ | ✔ | ✔ | Quarterly |
| LV | Latvia | ✔ | ✔ | ✔ | Quarterly |
| LR | Liberia | ✔ | ✔ | Quarterly | |
| LY | Libya | ✔ | ✔ | Quarterly | |
| LI | Liechtenstein | ✔ | ✔ | ✔ | Quarterly |
| LT | Lithuania | ✔ | ✔ | ✔ | Quarterly |
| LU | Luxembourg | ✔ | ✔ | ✔ | Quarterly |
| MO | Macao | ✔ | ✔ | ✔ | Quarterly |
| MG | Madagascar | ✔ | ✔ | Quarterly | |
| MW | Malawi | ✔ | ✔ | Quarterly | |
| MY | Malaysia | ✔ | ✔ | ✔ | Quarterly |
| MV | Maldives | ✔ | ✔ | Quarterly | |
| ML | Mali | ✔ | ✔ | Quarterly | |
| MT | Malta | ✔ | ✔ | ✔ | Quarterly |
| MQ | Martinique | ✔ | ✔ | ✔ | Quarterly |
| MR | Mauritania | ✔ | ✔ | Quarterly | |
| MU | Mauritius | ✔ | ✔ | Quarterly | |
| MX | Mexico | ✔ | ✔ | ✔ | Quarterly |
| MC | Monaco | ✔ | ✔ | ✔ | Quarterly |
| MN | Mongolia | ✔ | ✔ | Quarterly | |
| MD | Moldova | ✔ | ✔ | Quarterly | |
| ME | Montenegro | ✔ | ✔ | ✔ | Quarterly |
| MS | Montserrat | ✔ | ✔ | Quarterly | |
| MA | Morocco | ✔ | ✔ | ✔ | Quarterly |
| MZ | Mozambique | ✔ | ✔ | Quarterly | |
| OM | Oman | ✔ | ✔ | ✔ | Quarterly |
| NA | Namibia | ✔ | ✔ | ✔ | Quarterly |
| NR | Nauru | ✔ | Quarterly | ||
| NP | Nepal | ✔ | ✔ | Quarterly | |
| NL | Netherlands | ✔ | ✔ | ✔ | Quarterly |
| CW | Curacao | ✔ | ✔ | Quarterly | |
| AW | Aruba | ✔ | ✔ | Quarterly | |
| SX | Sint Maarten | ✔ | ✔ | Quarterly | |
| BQ | Bonaire, Sint Eustatius And Saba | ✔ | Quarterly | ||
| NC | New Caledonia | ✔ | ✔ | Quarterly | |
| VU | Vanuatu | ✔ | ✔ | Quarterly | |
| NZ | New Zealand | ✔ | ✔ | ✔ | Quarterly |
| NI | Nicaragua | ✔ | ✔ | Quarterly | |
| NE | Niger | ✔ | ✔ | Quarterly | |
| NG | Nigeria | ✔ | ✔ | Quarterly | |
| NU | Niue | ✔ | ✔ | Quarterly | |
| NF | Norfolk Island | ✔ | ✔ | Quarterly | |
| NO | Norway | ✔ | ✔ | ✔ | Quarterly |
| MP | Northern Mariana Islands | ✔ | ✔ | ✔ | Monthly |
| UM | United States Minor Outlying Islands | ✔ | Quarterly | ||
| FM | Micronesia | ✔ | ✔ | ✔ | Monthly |
| MH | Marshall Islands | ✔ | ✔ | ✔ | Monthly |
| PW | Palau | ✔ | ✔ | ✔ | Monthly |
| PK | Pakistan | ✔ | Quarterly | ||
| PA | Panama | ✔ | ✔ | ✔ | Quarterly |
| PG | Papua New Guinea | ✔ | ✔ | Quarterly | |
| PY | Paraguay | ✔ | ✔ | ✔ | Quarterly |
| PE | Peru | ✔ | ✔ | ✔ | Quarterly |
| PH | Philippines | ✔ | ✔ | ✔ | Quarterly |
| PN | Pitcairn | ✔ | Quarterly | ||
| PL | Poland | ✔ | ✔ | ✔ | Quarterly |
| PT | Portugal | ✔ | ✔ | ✔ | Quarterly |
| GW | Guinea-Bissau | ✔ | ✔ | Quarterly | |
| TL | Timor-Leste | ✔ | Quarterly | ||
| PR | Puerto Rico | ✔ | ✔ | ✔ | Monthly |
| QA | Qatar | ✔ | ✔ | ✔ | Quarterly |
| RE | Réunion | ✔ | ✔ | ✔ | Quarterly |
| RO | Romania | ✔ | ✔ | ✔ | Quarterly |
| RU | Russia | ✔ | ✔ | ✔ | Quarterly |
| RW | Rwanda | ✔ | ✔ | Quarterly | |
| BL | Saint-Barthélemy | ✔ | ✔ | ✔ | Quarterly |
| SH | Saint Helena | ✔ | ✔ | Quarterly | |
| KN | St. Kitts and Nevis | ✔ | ✔ | Quarterly | |
| AI | Anguilla | ✔ | ✔ | Quarterly | |
| LC | Saint Lucia | ✔ | ✔ | Quarterly | |
| MF | Saint Martin | ✔ | ✔ | Quarterly | |
| PM | Saint Pierre and Miquelon | ✔ | ✔ | Quarterly | |
| VC | St. Vincent and Grenadines | ✔ | ✔ | Quarterly | |
| SM | San Marino | ✔ | ✔ | ✔ | Quarterly |
| ST | Sao Tomé and Principe | ✔ | ✔ | Quarterly | |
| SA | Saudi Arabia | ✔ | ✔ | ✔ | Quarterly |
| SN | Senegal | ✔ | ✔ | Quarterly | |
| RS | Serbia | ✔ | ✔ | ✔ | Quarterly |
| SC | Seychelles | ✔ | ✔ | Quarterly | |
| SL | Sierra Leone | ✔ | ✔ | Quarterly | |
| SG | Singapore | ✔ | ✔ | ✔ | Quarterly |
| SK | Slovakia | ✔ | ✔ | ✔ | Quarterly |
| VN | Viet Nam | ✔ | ✔ | ✔ | Quarterly |
| SI | Slovenia | ✔ | ✔ | ✔ | Quarterly |
| SO | Somalia | ✔ | ✔ | Quarterly | |
| ZA | South Africa | ✔ | ✔ | ✔ | Quarterly |
| ZW | Zimbabwe | ✔ | ✔ | ✔ | Quarterly |
| ES | Spain | ✔ | ✔ | ✔ | Quarterly |
| SS | South Sudan | ✔ | ✔ | Quarterly | |
| SD | Sudan | ✔ | Quarterly | ||
| EH | Western Sahara | ✔ | Quarterly | ||
| SR | Suriname | ✔ | ✔ | ✔ | Quarterly |
| SJ | Svalbard and Jan Mayen | ✔ | ✔ | Quarterly | |
| SZ | Swaziland | ✔ | ✔ | Quarterly | |
| SE | Sweden | ✔ | ✔ | ✔ | Quarterly |
| CH | Switzerland | ✔ | ✔ | ✔ | Quarterly |
| SY | Syria | ✔ | Quarterly | ||
| TJ | Tajikistan | ✔ | ✔ | Quarterly | |
| TH | Thailand | ✔ | ✔ | ✔ | Quarterly |
| TG | Togo | ✔ | ✔ | Quarterly | |
| TK | Tokelau | ✔ | ✔ | Quarterly | |
| TO | Tonga | ✔ | ✔ | Quarterly | |
| TT | Trinidad and Tobago | ✔ | ✔ | Quarterly | |
| AE | United Arab Emirates | ✔ | ✔ | ✔ | Quarterly |
| TN | Tunisia | ✔ | ✔ | ✔ | Quarterly |
| TR | Turkey | ✔ | ✔ | ✔ | Quarterly |
| TM | Turkmenistan | ✔ | ✔ | Quarterly | |
| TC | Turks and Caicos Is. | ✔ | ✔ | Quarterly | |
| TV | Tuvalu | ✔ | ✔ | Quarterly | |
| UG | Uganda | ✔ | ✔ | Quarterly | |
| UA | Ukraine | ✔ | ✔ | ✔ | Quarterly |
| MK | Macedonia, TFYR | ✔ | ✔ | ✔ | Quarterly |
| EG | Egypt | ✔ | ✔ | ✔ | Quarterly |
| UK | United Kingdom | ✔ | ✔ | ✔ | Daily |
| TZ | Tanzania | ✔ | ✔ | Quarterly | |
| US | United States of America | ✔ | ✔ | ✔ | Every two months |
| VI | United States Virgin Islands | ✔ | ✔ | ✔ | Monthly |
| BF | Burkina Faso | ✔ | ✔ | Quarterly | |
| UY | Uruguay | ✔ | ✔ | ✔ | Quarterly |
| UZ | Uzbekistan | ✔ | ✔ | Quarterly | |
| VE | Venezuela | ✔ | ✔ | Quarterly | |
| WF | Wallis and Futuna | ✔ | ✔ | Quarterly | |
| WS | Samoa | ✔ | ✔ | Quarterly | |
| YE | Yemen | ✔ | Quarterly | ||
| ZM | Zambia | ✔ | ✔ | Quarterly |
Country endpoint
Return a list of countries and their associated codes to make it easier to specify a country code in an international address lookup. This list conforms to ISO-3166.
Request URL
GET | https://ws.postcoder.com/pcw/[apikey]/countries
Example
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/countries
[
{
"countryname":"Afghanistan",
"iso2":"AF",
"iso3":"AFG",
"iso3number":"4"
},
{
"countryname":"Aland Islands",
"iso2":"AX",
"iso3":"ALA",
"iso3number":"248"
},
...
]Tips
- Note that ISO-3166 specifies "GB" as the code for the United Kingdom. You can use this in your calls, but in our examples we use "UK" as the United Kingdom is not synonymous with Great Britain as the GB code might suggest.
- Use
countrynameto populate your list of countries andiso2as the country code in your calls to address lookup endpoints.
AddressBase API for address lookup
Postcoder provides you with access to AddressBase Core and AddressBase Premium through an API using the latest data from Ordnance Survey.
You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.
About AddressBase
AddressBase is a suite of data products from Ordnance Survey built from council records. Councils add records to a national data hub which is used by an organisation called GeoPlace to generate rich datasets showing how the United Kingdom is made up.
Ordnance Survey is the national mapping agency for Great Britain; there is a separate agency for Northern Ireland and others for the Crown Dependencies in the Channel Islands. AddressBase products therefore only provide data for the British mainland plus the Shetland Isles, Orkney, the Hebrides, the Isle of Wight and the Scilly Isles.
Use cases for AddressBase
- Navigation and mapping applications can make use of property level coordinates. Coordinates are available in terms of Eastings and Northings or Latitude and Longitude using coordinates common to online maps, GPS and sat nav systems.
- If you are involved in delivering national infrastructure projects, the Unique Property Reference Number (UPRN) which identifies each building in Great Britain is a critical key field which ties into council records.
- If you have an interest in buildings and properties individually or collectively then you will want to have access to the keys in council records.
Help me choose between AddressBase Core and AddressBase Premium
AddressBase Core and AddressBase Premium are built from the same source data.
AddressBase Core is designed for people who want to know geographical positioning details for properties and people who are after keys into other systems. For many use cases involving property coordinates and UPRNs, the core data will suit your purposes very well.
AddressBase Core contains geographic rather than postal address details but also contains the crucial key fields that can be used to get a postal address from Royal Mail. The key fields to link to Royal Mail are the Unique Delivery Point Reference Number (UDPRN), which is Royal Mail’s recommended key, or you can use the composite key of Postcode + Delivery Point Suffix. These data elements are provided where it has been possible to match a record to PAF. Please note that in the vast majority of cases the geographic address and postal address as used by Royal Mail’s mail sortation systems is identical however remote and rural locations in particular will have very different addresses.
On the other hand if you need to know more in depth details about a property – for example you might want to know what sort of road it is on for assessing insurance quotes or you might want to know the date a particular property or street was first entered on council records – you will need the more in depth data provided by AddressBase Premium. AddressBase Premium also directly provides the postal routing address used by Royal Mail where it has been possible to match the records together. This means you can retrieve a correct postal address as well as a geographic address using AddressBase Premium.
AddressBase request URLs and examples
Once enabled, your API key determines whether you access AddressBase Core or AddressBase Premium.
Address lookup using AddressBase Core / Premium
GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/[postcode-or-address-fragment]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
UPRN lookup using AddressBase Core / Premium
GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/uprn/[single-uprn-or-comma-delimited-uprns]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/uprn/2630163102
?format=json
&identifier=mytestlookup
&lines=2
Address lookup using PAF enriched with AddressBase Core / Premium
GET | https://ws.postcoder.com/pcw/[apikey]/pafaddressbase/[postcode-or-address-fragment]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/pafaddressbase/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
DPA lookup using AddressBase Premium only
GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/dpa/[postcode-or-address-fragment]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpa/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpa/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase
LPI lookup using AddressBase Premium only
GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/lpi/[postcode-or-address-fragment]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/lpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/lpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase
DPA and LPI lookup using AddressBase Premium only
GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/dpalpi/[postcode-or-address-fragment]
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpalpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpalpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| lines | Sets the number of address lines over which to display the first part of each address in the response | 0, 1, 2, 3, 4 | 0 |
| include | Specifies the extra address fields to include within the address lines, using a comma-delimited list | county, posttown, postcode | |
| exclude | Specifies the address fields to exclude within the address lines, using a comma-delimited list | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | |
| addtags | Specifies the extra fields to include within the response, using a comma-delimited list. A value of 'addressbase' returns all data (except 'tile' data); the other values shown here allow you to return particular fields and groups of fields. In addition to these AddressBase-specific values, see the additional data fields | addressbase, uprn, deliverypointaddress, lpis, blpu, classifications, organisations, applicationcrossreferences, tile, latitude, longitude... | |
| callback | Sets the name of your JSONP callback function | ||
| page | Specifies the page of results to return where 0 is the first page | 0, 1, 2, 3... | 0 |
AddressBase response fields
The following fields are returned in the response for AddressBase Core:
| Field | Description |
|---|---|
| summaryline | The address given in a single field separated by commas. Where matched against PAF this is a postal address |
| organisation | Organisation name. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| departmentname | Where there is a distinct delivery point for receipt of mail for a department, the department name is indicated here. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| pobox | Where linked to a PAF PO Box holder, this is the PO Box number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| subbuildingname | Sub-building name – usually a unit number or flat number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| buildingname | Name of the building. For instance Nelson House. May or may not be further sub-divided. Often contains what Royal Mail would class as a Dependent Street. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| number | The street number. Note that this may be alpha numeric. E.g. 1A. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| uniquedeliverypointreferencenumber | Royal Mail’s unique identifier for a Delivery Point (i.e. where postal delivery staff go to deliver mail). Assigned by Royal Mail and only available where an address record has been matched against PAF. Provides a unique identifier and designed to be unique over the life time of a delivery point |
| premise | A concatenation of the Department, PO Box, Sub-building Name, Building Name and Number (in that order). Useful if you have a single field in your database for storing the premise |
| dependentstreet | A street that needs another one for access. For example a cul-de-sac or a named parade of shops on a main road |
| street | The main street on which a property is situated. Commonly seems to be a main road especially in rural and remote settings. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| doubledependentlocality | This is a smaller industrial estate or sub-division of a town or village. The data in this field comes from Royal Mail if the record has been matched to a delivery point but the equivalent data from council records goes into Dependentlocality |
| dependentlocality | This is analogous to Royal Mail’s Double Dependent Locality and is generally representative of retail parks or industrial estates. Source: Council records or, if PAF matched, Royal Mail |
| townname | This is analogous to Royal Mail’s Dependent Locality and represents a suburb or small town. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| posttown | Where an address record has been matched against PAF, this is the post town responsible for mail sorting. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records |
| postcode | This is the Postcode assigned by Royal Mail |
| deliverypointsuffix | The Delivery Point Suffix used by Royal Mail. This, along with a Postcode, provides a unique identifier for a delivery point at a point in time. Source: Royal Mail |
| latitude | This is the latitude on the ETRS89 projection. See rpc |
| longitude | This is the longitude on the ETRS89 projection. See rpc |
| grideasting | The Easting on Ordnance Survey’s British National Grid. The units are in metres to 2 decimal places. See rpc |
| gridnorthing | The Northing on Ordnance Survey’s British National Grid. The units are in metres to 2 decimal places. See rpc |
| uprn | The Unique Property Reference Number – the primary key field for AddressBase data. Assigned by GeoPlace or Ordnance Survey |
| parentuprn | Where a particular property is part of another one (for example a flat in a block of flats or a unit on a business park) the owning property’s UPRN is indicated here. Please note that this is not the same as Royal Mail’s multiple residence indicator for postal purposes but is a good indicator that this is not a stand-alone property |
| usrn | The Unique Street Reference Number – every street under council control has its own unique identifier and this is it |
| changecode | Indicates how this record was last amended on the national hub. AddressBase Core only |
| toid | The topographical identifier which associates this record with OS MasterMap. AddressBase Core only |
| classificationcode | Describes the classification of the property according to council records |
| rpc | Tells you how accurate the coordinates are. For safety critical applications this may be a particularly important field: 1 – Central Internal Position – The address is contained within an OS MasterMap Topography Later building and within 2.5m of its calculated centre. Or the coordinates represent the best possible position based on the nature of the premises 2- General Internal Position – The address is contained within an OS MasterMap Topography Later building but is more than 2.5m away from its calculated centre. Or the seed is in an internal position based on the nature of the premises 3 – Transitional Position – The address has been changed from Under Development to Live within the last 6 months. It has been captured to a high level of positional accuracy but pending large scale mapping updates still may be moved 4 – Street Location – The address is plotted in accordance with the declared street start and end coordinates 5 – Postcode Unit position – The address has been captured to Postcode Unit level and will be updated when more information becomes available. It is likely that every property on the Postcode will be sharing these same coordinates 9 – Low Accuracy – The address has been captured to a lower level of accuracy and will be updated as a priority over the coming months |
| gsscode | Provided by the Office for National Statistics and used for official records. Codes are structured: the first three characters are an Entity Code and the remaining 6 characters are the particular instance. Entity Codes are: E06 (Unitary Authority); E07 (Local Authority District Council); E08 (Metropolitan Borough Council); and E09 (London Borough) |
| lastupdatedate | The date this record was last updated |
Eircode API for Irish address lookup
Postcoder provides you with access to Eircode ECAD through an API using the latest data from Capita Ireland.
You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.
Eircode request URLs
Irish address lookup using Eircode
GET | https://ws.postcoder.com/pcw/[apikey]/address/ie/[eircode-or-address-fragment]
Irish reverse geocoding using Eircode
GET | https://ws.postcoder.com/pcw/[apikey]/rgeo/ie/[latitude]/[longitude]?distance=[distance-in-metres]
Irish geocoding using Eircode
GET | https://ws.postcoder.com/pcw/[apikey]/position/ie/[eircode]
Eircode request examples
Tip
Most but not all Irish addresses require a post town. Postcoder will return a post town in the response only when it is required.
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| lines | Sets the number of address lines over which to display the first part of each address in the response | 0, 1, 2, 3, 4 | 0 |
| include | Specifies the extra address fields to include within the address lines, using a comma-delimited list | county, posttown, postcode | |
| exclude | Specifies the address fields to exclude within the address lines, using a comma-delimited list | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | |
| language | Specifies the language to return the address in - either Irish (gle) or English (eng) | gle, eng | eng |
| callback | Sets the name of your JSONP callback function | ||
| page | Specifies the page of results to return where 0 is the first page | 0, 1, 2, 3... | 0 |
Not Yet Built API for addresses under construction
Postcoder provides you with access to Not Yet Built through an API using the latest data from Royal Mail.
You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.
NYB request URL
GET | https://ws.postcoder.com/pcw/[apikey]/nyb/uk/[postcode-or-address-fragment]
NYB request example
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| lines | Sets the number of address lines over which to display the first part of each address in the response | 0, 1, 2, 3, 4 | 0 |
| include | Specifies the extra address fields to include within the address lines, using a comma-delimited list | county, posttown, postcode | |
| exclude | Specifies the address fields to exclude within the address lines, using a comma-delimited list | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | |
| addtags | Specifies the extra address fields to include within the response, using a comma-delimited list | See Additional data fields | |
| callback | Sets the name of your JSONP callback function | ||
| page | Specifies the page of results to return where 0 is the first page | 0, 1, 2, 3... | 0 |
UK geocoding
Lookup coordinates for a postcode in the UK.
Uses the latest data from the Office for National Statistics.
Example code
Request URL
Postcode to geodata
GET | https://ws.postcoder.com/pcw/[apikey]/position/uk/[postcode]
Full address with geodata
GET | https://ws.postcoder.com/pcw/[apikey]/address/uk/[postcode-or-address-fragment]?addtags=latitude,longitude
Try it now
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| callback | Sets the name of your JSONP callback function |
UK reverse geocoding
Lookup street addresses in the UK using latitude and longitude.
Uses the latest data from Royal Mail and the Office for National Statistics.
Request URL
GET | https://ws.postcoder.com/pcw/[apikey]/rgeo/uk/[latitude]/[longitude]?distance=[distance-in-metres]
Example
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| callback | Sets the name of your JSONP callback function |
UK street lookup
Lookup the UK street(s) for a postcode.
Uses the latest PAF and Multiple Residence data from Royal Mail.
Request URL
GET | https://ws.postcoder.com/pcw/[apikey]/street/uk/[postcode]
Example
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| callback | Sets the name of your JSONP callback function |
UDPRN lookup
Lookup a UK address using a UDPRN.
Uses the latest PAF and Multiple Residence data from Royal Mail.
Request URL
GET | https://ws.postcoder.com/pcw/[apikey]/udprn/[udprn]
Example
Optional querystring parameters
| Parameter | Description | Values | Default |
|---|---|---|---|
| format | Sets the data format of the response; the default is json unless header of application/xml is detected | xml, json | json |
| identifier | Sets an identifier like "checkout" or "contactform" to help you group requests within your search history | ||
| lines | Sets the number of address lines over which to display the first part of each address in the response | 0, 1, 2, 3, 4 | 0 |
| include | Specifies the extra address fields to include within the address lines, using a comma-delimited list | county, posttown, postcode | |
| exclude | Specifies the address fields to exclude within the address lines, using a comma-delimited list | pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality | |
| addtags | Specifies the extra address fields to include within the response, using a comma-delimited list | See Additional data fields | |
| callback | Sets the name of your JSONP callback function |
Paging
Up to 100 results can be returned at a time in response to a lookup. If there are more results beyond the current page for a UK or Eircode address search, the last result will include a morevalues field with a value of true.
We also include a nextpage field with the number of the next page, so you can easily append ?page=[nextpage] to your request. The totalresults field lets you know how many results in total have been returned by your search.
Notes:
- First page = 0, second page = 1, etc...
- If there are no more results beyond the current page, the
morevaluesfield will not be present.
