International address lookup

Returns addresses within any country for a postal code (e.g. 20500) or address fragment (e.g. 1600 Pennsylvania).

Lookup costs:
UK and international addresses: 2 credits
Irish addresses with Eircodes: 4.5 credits

Request structure

http://ws.postcoder.com/pcw/[api-key]/address/[country-code]/[postcode-or-address-fragment]

Optional parameters

lines The number of lines over which to split each address
include Include extra address fields within the address lines returned (see above)
exclude Exclude address fields within the address lines returned (see above)
format xml | json (default unless header of application/xml is detected)
identifier Identify your lookups to make debugging and reviewing stats easier
callback Use to specify the name of your JSONP callback function
postcodeonly Use ?postcodeonly=true to limit your search to just the postcode field.

Notes

  • Specify the [country-code] within your request using the 2 letter ISO 3166-1 country code - see country list below
  • Multiple addresses may be returned depending on your search criteria
  • Empty address fields are not returned in the response, so all fields should be treated as optional
  • We recommend using Latin characters to perform lookups where possible
  • Response fields are formatted based on the S42 standard from the Universal Postal Union (UPU)
  • The include and exclude parameters are only available with the UK, US and IE (Eircode) datasets

Response examples

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/us/20500-0001?lines=5&format=json - View live response

[
    {
        "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",
        "organisation" : "President",
        "number" : "1600",
        "premise" : "1600",
        "street" : "Pennsylvania Ave NW",
        "posttown" : "Washington",
        "county" : "DC",
        "postcode" : "20500-0001"
    }
]

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/us/20500-0001?lines=5&format=xml - View live response

<Addresses xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Address>
        <addressline1>PRESIDENT</addressline1>
        <addressline2>1600 PENNSYLVANIA AVE NW</addressline2>
        <addressline3>WASHINGTON DC 20500-0001</addressline3>
        <addressline4>UNITED STATES</addressline4>
        <summaryline>President, 1600 Pennsylvania Ave NW, Washington, DC, 20500-0001</summaryline>
        <organisation>President</organisation>
        <number>1600</number>
        <premise>1600</premise>
        <street>Pennsylvania Ave NW</street>
        <posttown>Washington</posttown>
        <county>DC</county>
        <postcode>20500-0001</postcode>
    </Address>
</Addresses>

Response field descriptions

Field name Data type Description Example
summaryline String Summary President, 1600 Pennsylvania Ave NW, Washington, DC, 20500-0001
pobox String PO Box
organisation String Organisation President
departmentname String Department name
number String Building number 1600
premise String Premise description including building number, name and sub-building 1600
dependentstreet String Dependent street
street String Street Pennsylvania Ave NW
doubledependentlocality String Double dependent locality
dependentlocality String Dependent locality
posttown String Post town Washington
county String County or state DC
postcode String Postal code 20500-0001

Global coverage

CountryBuildingsStreetsTownsCountry Code
AfghanistanAF
Aland IslandsAX
AlbaniaAL
AlgeriaDZ
American SamoaAS
AndorraAD
AngolaAO
AnguillaAI
AntarcticaAQ
Antigua and BarbudaAG
ArgentinaAR
ArmeniaAM
ArubaAW
AustraliaAU
AustriaAT
AzerbaijanAZ
BahamasBS
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BelizeBZ
BeninBJ
BermudaBM
BhutanBT
BoliviaBO
Bonaire, Sint Eustatius And SabaBQ
Bosnia and HerzegovinaBA
BotswanaBW
Br. Indian Ocean Ter.IO
BrazilBR
Brunei DarussalamBN
BulgariaBG
Burkina FasoBF
BurundiBI
CambodiaKH
CameroonCM
CanadaCA
Cape VerdeCV
Cayman IslandsKY
Central African Rep.CF
ChadTD
ChileCL
ChinaCN
Christmas IslandCX
Cocos (Keeling) IslandsCC
ColombiaCO
ComorosKM
Congo (Dem. Rep.)CD
Congo (Rep.)CG
Cook IslandsCK
Costa RicaCR
Côte d'IvoireCI
CroatiaHR
CubaCU
CuracaoCW
CyprusCY
Czech RepublicCZ
DenmarkDK
DjiboutiDJ
DominicaDM
Dominican RepublicDO
EcuadorEC
EgyptEG
El SalvadorSV
Equatorial GuineaGQ
EritreaER
EstoniaEE
EthiopiaET
Falkland Is. (Malvinas)FK
Faröe IslandsFO
FijiFJ
FinlandFI
FranceFR
French GuianaGF
French PolynesiaPF
French Southern TerritoriesTF
GabonGA
GambiaGM
GeorgiaGE
GermanyDE
GhanaGH
GibraltarGI
GreeceGR
GreenlandGL
GrenadaGD
GuadeloupeGP
GuamGU
GuatemalaGT
GuineaGN
Guinea-BissauGW
GuyanaGY
HaitiHT
HondurasHN
Hong KongHK
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
IranIR
IraqIQ
IrelandIE
IsraelIL
ItalyIT
JamaicaJM
JapanJP
JordanJO
KazakhstanKZ
KenyaKE
KiribatiKI
Korea (Dem. Rep.)KP
Korea (Rep.)KR
KuwaitKW
KyrgyzstanKG
LaosLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LibyaLY
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacaoMO
Macedonia, TFYRMK
MadagascarMG
MalawiMW
MalaysiaMY
MaldivesMV
MaliML
MaltaMT
Marshall IslandsMH
MartiniqueMQ
MauritaniaMR
MauritiusMU
MayotteYT
MexicoMX
MicronesiaFM
MoldovaMD
MonacoMC
MongoliaMN
MontenegroME
MontserratMS
MoroccoMA
MozambiqueMZ
MyanmarMM
NamibiaNA
NauruNR
NepalNP
NetherlandsNL
New CaledoniaNC
New ZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
NiueNU
Norfolk IslandNF
Northern Mariana IslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
Palestinian TerritoryPS
PanamaPA
Papua New GuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PitcairnPN
PolandPL
PortugalPT
Puerto RicoPR
QatarQA
RéunionRE
RomaniaRO
RussiaRU
RwandaRW
S. Georgia and S. SandwichGS
Saint HelenaSH
Saint LuciaLC
Saint MartinMF
Saint Pierre and MiquelonPM
Saint-BarthélemyBL
SamoaWS
San MarinoSM
Sao Tomé and PrincipeST
Saudi ArabiaSA
SenegalSN
SerbiaRS
SeychellesSC
Sierra LeoneSL
SingaporeSG
Sint MaartenSX
SlovakiaSK
SloveniaSI
Solomon IslandsSB
SomaliaSO
South AfricaZA
South SudanSS
SpainES
Sri LankaLK
St. Kitts and NevisKN
St. Vincent and GrenadinesVC
SudanSD
SurinameSR
Svalbard and Jan MayenSJ
SwazilandSZ
SwedenSE
SwitzerlandCH
SyriaSY
TaiwanTW
TajikistanTJ
TanzaniaTZ
ThailandTH
Timor-LesteTL
TogoTG
TokelauTK
TongaTO
Trinidad and TobagoTT
TunisiaTN
TurkeyTR
TurkmenistanTM
Turks and Caicos Is.TC
TuvaluTV
UgandaUG
UkraineUA
United Arab EmiratesAE
United KingdomGB
United States Minor Outlying IslandsUM
United States of AmericaUS
United States Virgin IslandsVI
UruguayUY
UzbekistanUZ
VanuatuVU
Vatican CityVA
VenezuelaVE
Viet NamVN
Virgin Islands, BritishVG
Wallis and FutunaWF
Western SaharaEH
YemenYE
ZambiaZM
ZimbabweZW