Supported Countries

The Find Address API searches addresses in 243 countries and territories, served by 20 datasets. The table at the foot of this page lists every country with how fine its coverage is and the context value that selects it.

Switching country with context

Searches run against the United States unless you say otherwise. Pass context with the country's ISO 3166-1 alpha-3 code to search elsewhere. The code is the Context column of the table below and the country_iso field of every returned address.

Find Address takes context as a query parameter. The Address Lookup widget exposes the same switch through defaultCountry, restrictCountries and contexts.

Codes are case-insensitive. A code the API does not recognise is ignored and the search falls back to the United States.

The requests below use the ak_test key, so they run as written.

United States

curl -G https://api.addresszen.com/v1/autocomplete/addresses \
  --data-urlencode "api_key=ak_test" \
  --data-urlencode "query=1600 pennsylvania ave" \
  --data-urlencode "context=USA" \
  --data-urlencode "limit=2"

{
  "result": {
    "hits": [
      {
        "suggestion": "1600 Pennsylvania Ave, Linden, NJ, 07036",
        "urls": {},
        "id": "usps_V122200597|1600||17ND"
      },
      {
        "suggestion": "1600 Pennsylvania Ave, Stoughton, MA, 02072",
        "urls": {},
        "id": "usps_V213109465|1600||2318"
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

United Kingdom

curl -G https://api.addresszen.com/v1/autocomplete/addresses \
  --data-urlencode "api_key=ak_test" \
  --data-urlencode "query=10 downing street" \
  --data-urlencode "context=GBR" \
  --data-urlencode "limit=2"

{
  "result": {
    "hits": [
      {
        "id": "paf_824800",
        "suggestion": "10 Downing Street, Halesowen, B63",
        "udprn": 824800,
        "urls": {
          "udprn": "/v1/udprn/824800"
        }
      },
      {
        "id": "paf_12522372",
        "suggestion": "10 Downing Street, Liverpool, L5",
        "udprn": 12522372,
        "urls": {
          "udprn": "/v1/udprn/12522372"
        }
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

Ireland

curl -G https://api.addresszen.com/v1/autocomplete/addresses \
  --data-urlencode "api_key=ak_test" \
  --data-urlencode "query=1 grafton street" \
  --data-urlencode "context=IRL" \
  --data-urlencode "limit=2"

{
  "result": {
    "hits": [
      {
        "id": "herewe_pap|uEXlTCwRpMmtSYizTlZnQ|en",
        "suggestion": "Apartment 1, Grafton Hall, 38-40 Aungier Street, Dublin 2, Dublin, D02 Y680",
        "urls": {}
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

The coverage JSON

GET https://api.addresszen.com/coverage.json returns the data behind the table on this page. It needs no API key. The body holds a coverage array with one object per country and dataset pair, so a country served by two datasets appears twice.

Field	Type	Meaning
dataset_id	string	Short code for the dataset, e.g. usps
dataset_name	string	The dataset's full name
country_name	string	Country or territory name
country_iso	string	ISO 3166-1 alpha-3 code. Pass it as context to search this country
coverage_level	string	The finest address element the dataset resolves: Sub-building, Building, Street, Locality or Region
update_frequency	string	How often the data refreshes: Daily, Weekly, Monthly or Quarterly
postal_code	boolean	Whether addresses carry a postal code
unique_identifiers	string[]	Identifiers returned on each address, e.g. uprn, udprn, Eircode. Empty when the dataset has none

{
  "coverage": [
    {
      "dataset_id": "usps",
      "dataset_name": "USPS",
      "country_name": "United States",
      "country_iso": "USA",
      "coverage_level": "Sub-building",
      "update_frequency": "Monthly",
      "postal_code": true,
      "unique_identifiers": ["zip_plus_four_code"]
    }
  ]
}

Coverage by country

Coverage levels, finest first:

• Sub-building: individual flats, apartments and units within a building
• Building: each building or premise
• Street: the street, without a premise number
• Locality: the town or district
• Region: the region or state

Where two datasets cover a country the table shows the finest coverage level and merges their identifiers. The API answers from the richer dataset.

Country	Context	Coverage	Postcode	Updated	Identifiers
Afghanistan	AFG	Locality	No	Quarterly
Albania	ALB	Building	Yes	Quarterly
Algeria	DZA	Street	No	Quarterly
American Samoa	ASM	Sub-building	Yes	Monthly	zip_plus_four_code
Andorra	AND	Building	Yes	Quarterly
Angola	AGO	Street	No	Quarterly
Anguilla	AIA	Street	No	Quarterly
Antigua and Barbuda	ATG	Street	No	Quarterly
Argentina	ARG	Building	Yes	Quarterly
Armenia	ARM	Building	No	Quarterly
Aruba	ABW	Building	No	Quarterly
Australia	AUS	Sub-building	Yes	Quarterly	G-NAF PID
Austria	AUT	Building	Yes	Quarterly
Azerbaijan	AZE	Building	No	Quarterly
Bahamas	BHS	Building	No	Quarterly
Bahrain	BHR	Building	No	Quarterly
Bangladesh	BGD	Street	No	Quarterly
Barbados	BRB	Street	No	Quarterly
Belarus	BLR	Building	Yes	Quarterly
Belgium	BEL	Building	Yes	Quarterly
Belize	BLZ	Street	No	Quarterly
Benin	BEN	Street	No	Quarterly
Bermuda	BMU	Building	Yes	Quarterly
Bhutan	BTN	Locality	No	Quarterly
Bolivia	BOL	Building	No	Quarterly
Bonaire, Sint Eustatius and Saba	BES	Street	No	Quarterly
Bosnia and Herzegovina	BIH	Building	Yes	Quarterly
Botswana	BWA	Building	No	Quarterly
Brazil	BRA	Building	Yes	Quarterly
British Indian Ocean Territory	IOT	Region	No	Quarterly
British Virgin Islands	VGB	Building	No	Quarterly
Brunei Darussalam	BRN	Building	Yes	Quarterly
Bulgaria	BGR	Building	Yes	Quarterly
Burkina Faso	BFA	Locality	No	Quarterly
Burundi	BDI	Street	No	Quarterly
Cambodia	KHM	Building	No	Quarterly
Cameroon	CMR	Street	No	Quarterly
Canada	CAN	Building	No	Quarterly
Cape Verde	CPV	Street	No	Quarterly
Cayman Islands	CYM	Building	Yes	Quarterly
Central African Republic	CAF	Street	No	Quarterly
Chad	TCD	Street	No	Quarterly
Chile	CHL	Building	Yes	Quarterly
China	CHN	Locality	No	Quarterly
Christmas Island	CXR	Sub-building	Yes	Quarterly	G-NAF PID
Cocos (Keeling) Islands	CCK	Sub-building	Yes	Quarterly	G-NAF PID
Colombia	COL	Building	Yes	Quarterly
Comoros	COM	Locality	No	Quarterly
Cook Islands	COK	Street	No	Quarterly
Costa Rica	CRI	Building	Yes	Quarterly
Côte d'Ivoire	CIV	Street	No	Quarterly
Croatia	HRV	Building	Yes	Quarterly
Cuba	CUB	Street	No	Quarterly
Curaçao	CUW	Street	No	Quarterly
Cyprus	CYP	Building	Yes	Quarterly
Czech Republic	CZE	Building	Yes	Quarterly
Democratic Republic of the Congo	COD	Street	No	Quarterly
Denmark	DNK	Building	Yes	Quarterly
Djibouti	DJI	Street	No	Quarterly
Dominica	DMA	Street	No	Quarterly
Dominican Republic	DOM	Building	Yes	Quarterly
Ecuador	ECU	Building	Yes	Quarterly
Egypt	EGY	Building	No	Quarterly
El Salvador	SLV	Building	No	Quarterly
Equatorial Guinea	GNQ	Locality	No	Quarterly
Eritrea	ERI	Locality	No	Quarterly
Estonia	EST	Building	Yes	Quarterly
Eswatini	SWZ	Building	Yes	Quarterly
Ethiopia	ETH	Street	No	Quarterly
Falkland Islands (Malvinas)	FLK	Street	Yes	Quarterly
Faroe Islands	FRO	Building	Yes	Quarterly
Federated States of Micronesia	FSM	Sub-building	Yes	Monthly	zip_plus_four_code
Fiji	FJI	Building	No	Quarterly
Finland	FIN	Building	Yes	Quarterly
France	FRA	Building	Yes	Quarterly
French Guiana	GUF	Building	Yes	Quarterly
French Polynesia	PYF	Street	No	Quarterly
Gabon	GAB	Locality	No	Quarterly
Gambia	GMB	Locality	No	Quarterly
Georgia	GEO	Building	No	Quarterly
Germany	DEU	Building	Yes	Quarterly
Ghana	GHA	Building	No	Quarterly
Gibraltar	GIB	Building	Yes	Quarterly
Greece	GRC	Building	Yes	Quarterly
Greenland	GRL	Building	No	Quarterly
Grenada	GRD	Street	No	Quarterly
Guadeloupe	GLP	Building	Yes	Quarterly
Guam	GUM	Sub-building	Yes	Monthly	zip_plus_four_code
Guatemala	GTM	Building	Yes	Quarterly
Guernsey	GGY	Sub-building	Yes	Weekly, Daily	uprn, udprn
Guinea	GIN	Street	No	Quarterly
Guinea-Bissau	GNB	Street	No	Quarterly
Guyana	GUY	Locality	No	Quarterly
Haiti	HTI	Street	No	Quarterly
Honduras	HND	Street	No	Quarterly
Hong Kong	HKG	Building	No	Quarterly
Hungary	HUN	Building	Yes	Quarterly
Iceland	ISL	Building	Yes	Quarterly
India	IND	Building	Yes	Quarterly
Indonesia	IDN	Building	Yes	Quarterly
Iran	IRN	Locality	No	Quarterly
Iraq	IRQ	Street	No	Quarterly
Ireland	IRL	Sub-building	Yes	Monthly, Quarterly	Eircode
Isle of Man	IMN	Sub-building	Yes	Weekly, Daily	uprn, udprn
Israel	ISR	Building	Yes	Quarterly
Italy	ITA	Building	Yes	Quarterly
Jamaica	JAM	Building	No	Quarterly
Japan	JPN	Locality	No	Quarterly
Jersey	JEY	Sub-building	Yes	Weekly, Daily	uprn, udprn
Jordan	JOR	Building	No	Quarterly
Kazakhstan	KAZ	Building	Yes	Quarterly
Kenya	KEN	Street	No	Quarterly
Kiribati	KIR	Locality	No	Quarterly
Kosovo	XKX	Building	Yes	Quarterly
Kuwait	KWT	Building	No	Quarterly
Kyrgyzstan	KGZ	Building	No	Quarterly
Laos	LAO	Locality	No	Quarterly
Latvia	LVA	Building	Yes	Quarterly
Lebanon	LBN	Building	No	Quarterly
Lesotho	LSO	Building	No	Quarterly
Liberia	LBR	Locality	No	Quarterly
Libya	LBY	Street	No	Quarterly
Liechtenstein	LIE	Building	Yes	Quarterly
Lithuania	LTU	Building	Yes	Quarterly
Luxembourg	LUX	Building	Yes	Quarterly
Macau	MAC	Building	No	Quarterly
Madagascar	MDG	Locality	No	Quarterly
Malawi	MWI	Street	No	Quarterly
Malaysia	MYS	Building	Yes	Quarterly
Maldives	MDV	Locality	No	Quarterly
Mali	MLI	Locality	No	Quarterly
Malta	MLT	Building	No	Quarterly
Marshall Islands	MHL	Sub-building	Yes	Monthly	zip_plus_four_code
Martinique	MTQ	Building	Yes	Quarterly
Mauritania	MRT	Street	No	Quarterly
Mauritius	MUS	Building	No	Quarterly
Mayotte	MYT	Building	Yes	Quarterly
Mexico	MEX	Building	Yes	Quarterly
Moldova	MDA	Building	Yes	Quarterly
Monaco	MCO	Building	Yes	Quarterly
Mongolia	MNG	Locality	No	Quarterly
Montenegro	MNE	Building	Yes	Quarterly
Montserrat	MSR	Locality	No	Quarterly
Morocco	MAR	Building	No	Quarterly
Mozambique	MOZ	Street	Yes	Quarterly
Myanmar	MMR	Building	No	Quarterly
Namibia	NAM	Building	No	Quarterly
Nauru	NRU	Region	No	Quarterly
Nepal	NPL	Locality	No	Quarterly
Netherlands	NLD	Sub-building	Yes	Quarterly, Monthly
New Caledonia	NCL	Building	No	Quarterly
New Zealand	NZL	Building	Yes	Quarterly
Nicaragua	NIC	Building	No	Quarterly
Niger	NER	Locality	No	Quarterly
Nigeria	NGA	Building	No	Quarterly
Niue	NIU	Locality	No	Quarterly
Norfolk Island	NFK	Sub-building	Yes	Quarterly	G-NAF PID
North Korea	PRK	Locality	No	Quarterly
North Macedonia	MKD	Building	Yes	Quarterly
Northern Mariana Islands	MNP	Sub-building	Yes	Monthly	zip_plus_four_code
Norway	NOR	Sub-building	Yes	Quarterly, Weekly
Oman	OMN	Building	No	Quarterly
Pakistan	PAK	Locality	No	Quarterly
Palau	PLW	Sub-building	Yes	Monthly	zip_plus_four_code
Panama	PAN	Building	No	Quarterly
Papua New Guinea	PNG	Locality	No	Quarterly
Paraguay	PRY	Building	Yes	Quarterly
Peru	PER	Building	Yes	Quarterly
Philippines	PHL	Building	Yes	Quarterly
Pitcairn Islands	PCN	Locality	No	Quarterly
Poland	POL	Building	Yes	Quarterly
Portugal	PRT	Building	Yes	Quarterly
Puerto Rico	PRI	Sub-building	Yes	Monthly	zip_plus_four_code
Qatar	QAT	Building	No	Quarterly
Republic of the Congo	COG	Street	No	Quarterly
Réunion	REU	Building	Yes	Quarterly
Romania	ROU	Building	Yes	Quarterly
Russia	RUS	Building	Yes	Quarterly
Rwanda	RWA	Street	No	Quarterly
Saint Barthélemy	BLM	Building	Yes	Quarterly
Saint Helena, Ascension and Tristan da Cunha	SHN	Street	No	Quarterly
Saint Kitts and Nevis	KNA	Locality	No	Quarterly
Saint Lucia	LCA	Locality	No	Quarterly
Saint Martin (French part)	MAF	Building	Yes	Quarterly
Saint Pierre and Miquelon	SPM	Street	No	Quarterly
Saint Vincent and the Grenadines	VCT	Street	No	Quarterly
Samoa	WSM	Street	No	Quarterly
San Marino	SMR	Building	Yes	Quarterly
São Tomé and Príncipe	STP	Street	No	Quarterly
Saudi Arabia	SAU	Building	Yes	Quarterly
Senegal	SEN	Building	No	Quarterly
Serbia	SRB	Building	Yes	Quarterly
Seychelles	SYC	Locality	No	Quarterly
Sierra Leone	SLE	Street	No	Quarterly
Singapore	SGP	Building	No	Quarterly
Sint Maarten (Dutch part)	SXM	Locality	No	Quarterly
Slovakia	SVK	Building	Yes	Quarterly
Slovenia	SVN	Building	Yes	Quarterly
Solomon Islands	SLB	Street	No	Quarterly
Somalia	SOM	Locality	No	Quarterly
South Africa	ZAF	Building	Yes	Quarterly
South Georgia and the South Sandwich Islands	SGS	Locality	No	Quarterly
South Korea	KOR	Locality	No	Quarterly
South Sudan	SSD	Locality	No	Quarterly
Spain	ESP	Building	Yes	Quarterly
Sri Lanka	LKA	Building	No	Quarterly
Sudan	SDN	Locality	No	Quarterly
Suriname	SUR	Building	No	Quarterly
Svalbard and Jan Mayen	SJM	Sub-building	Yes	Quarterly, Weekly
Sweden	SWE	Building	Yes	Quarterly
Switzerland	CHE	Building	Yes	Quarterly
Syria	SYR	Locality	No	Quarterly
Taiwan	TWN	Building	Yes	Quarterly
Tajikistan	TJK	Locality	No	Quarterly
Tanzania	TZA	Street	No	Quarterly
Thailand	THA	Building	Yes	Quarterly
Timor-Leste	TLS	Locality	No	Quarterly
Togo	TGO	Street	No	Quarterly
Tokelau	TKL	Region	No	Quarterly
Tonga	TON	Street	No	Quarterly
Trinidad and Tobago	TTO	Building	No	Quarterly
Tunisia	TUN	Building	No	Quarterly
Turkey	TUR	Building	Yes	Quarterly
Turkmenistan	TKM	Locality	No	Quarterly
Turks and Caicos Islands	TCA	Locality	Yes	Quarterly
Tuvalu	TUV	Locality	No	Quarterly
Uganda	UGA	Street	No	Quarterly
Ukraine	UKR	Building	Yes	Quarterly
United Arab Emirates	ARE	Building	No	Quarterly
United Kingdom	GBR	Sub-building	Yes	Weekly, Daily	uprn, udprn
United States	USA	Sub-building	Yes	Monthly	zip_plus_four_code
United States Virgin Islands	VIR	Sub-building	Yes	Monthly	zip_plus_four_code
Uruguay	URY	Building	Yes	Quarterly
Uzbekistan	UZB	Building	No	Quarterly
Vanuatu	VUT	Building	No	Quarterly
Vatican City	VAT	Building	Yes	Quarterly
Venezuela	VEN	Building	No	Quarterly
Vietnam	VNM	Building	Yes	Quarterly
Wallis and Futuna	WLF	Street	No	Quarterly
Western Sahara	ESH	Street	No	Quarterly
Yemen	YEM	Street	No	Quarterly
Zambia	ZMB	Building	No	Quarterly
Zimbabwe	ZWE	Building	No	Quarterly