Verify international addresses

This page describes how to verify an address using the SmartyStreets International API.

Contents

  1. Input fields
  2. Verify only
  3. Verify and geocode
  4. Output fields
  5. Supported countries

Input fields

The minimum requirements for a positive address match are:
freeform + country
OR
address1 + postal_code + country
OR
address1 + locality + administrative_area + country

Name Type Max Characters Description
input_id string 16 A unique identifier generated by you for this address for use within your application; this field will be copied into the output.
(e.g., 123456)
country string 64 (required) This must be entered with every address. Country Name or ISO classification (ISO-3, ISO-2 or ISO-N). Address validation will fail if this is missing.
(e.g., Brazil, BRA, BR, or 076)
geocode string 4 Set to true to enable geocoding (disabled by default). Additional geocoding charges apply when enabled.
freeform string 512 The entire address in a single field (without the country). If freeform is specified, all other address input fields (except country) will be ignored.
(e.g., Via Santa Maria di Costantinopoli, 72 46030-Tabellano MN)
address1 string 64 The first address line.
(e.g., Calle Proc. San Sebastián, 15)
address2 string 64 The second address line (if any).
address3 string 64 The third address line (if any).
address4 string 64 The fourth address line (if any).
organization string 64 The name of the recipient, firm, or company at this address.
(e.g., Robert Smith OR The Clean Oil Company)
locality string 64 The city name.
(e.g., Paris)
administrative_area string 32 The state or province name or abbreviation.
(e.g., Alberta or AB)
postal_code string 16 The postal code.
(e.g., 90210-2301)

Verify only (no geocodes)

Request

curl -v 'https://international-api.smartystreets.com/verify?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&
	address1=Rua+Padre+Antonio+D%27Angelo+121&
	address2=Casa+Verde&
	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil'

Response

Every response is a JSON array containing zero or more address matches for your input.

[
	{
		"address1":"Rua Padre Antônio D'ângelo 121",
		"address2":"Casa Verde",
		"address3":"02516-040 São Paulo SP",
		"country":"Brazil",
		"components":{
			"administrative_area":"SP",
			"dependent_locality":"Casa Verde",
			"country_iso_2":"BR",
			"country_iso_3":"BRA",
			"country_iso_n":"076",
			"locality":"São Paulo",
			"postal_code":"02516-040",
			"postal_code_short":"02516-040",
			"premise":"121",
			"premise_number":"121",
			"thoroughfare":"Rua Padre Antônio D'ângelo",
			"thoroughfare_name":"Padre Antonio D'angelo",
			"thoroughfare_type":"Rua"
		},
		"metadata":{

		},
		"analysis":{
			"verification_status":"Verified",
			"address_precision":"Premise"
		}
	}
]

Verify and geocode

Request

curl -v 'https://international-api.smartystreets.com/verify?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&
	address1=Rua+Padre+Antonio+D%27Angelo+121&
	address2=Casa+Verde&
	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil&
	geocode=true'

Response

Every response is a JSON array containing zero or more address matches for your input.

[
	{
		"address1":"Rua Padre Antônio D'ângelo 121",
		"address2":"Casa Verde",
		"address3":"02516-040 São Paulo SP",
		"country":"Brazil",
		"components":{
			"administrative_area":"SP",
			"dependent_locality":"Casa Verde",
			"country_iso_2":"BR",
			"country_iso_3":"BRA",
			"country_iso_n":"076",
			"locality":"São Paulo",
			"postal_code":"02516-040",
			"postal_code_short":"02516-040",
			"premise":"121",
			"premise_number":"121",
			"thoroughfare":"Rua Padre Antônio D'ângelo",
			"thoroughfare_name":"Padre Antonio D'angelo",
			"thoroughfare_type":"Rua"
		},
		"metadata":{
			"latitude":-23.50948,
			"longitude":-46.66073,
			"geocode_precision":"Premise"
		},
		"analysis":{
			"verification_status":"Verified",
			"address_precision":"Premise"
		}
	}
]

Output fields

Root  |  Components  |  Metadata  |  Analysis

Root

Field Name Type Definition
input_id varchar(16) A unique identifier generated by you for this address for use within your application. The output will be identical to the value you provided in the request input_id.
organization varchar(256) The name of the recipient, firm, or company at this address. The output will be identical to the input.
address1-12 varchar(256) If verification_status = verified these fields will contain the correctly formatted address for mailing in the relevant country, split into individual address lines.

If verification_statusverified the address fields may contain standardized address information or even the original input data.
country varchar(256) This field holds the ISO 3166 official country name.
components [Object] See "Components" table below. Contains the various basic elements of the address.
metadata [Object] See "Metadata" table below. Contains ancillary data about each address.
analysis [Object] See "Analysis" table below. Contains information about the validation and the precision of the output address.

Components

Field Name Type Definition
super_administrative_area varchar(64) The largest administrative divsion within a country.
(e.g., Region in France.)
administrative_area varchar(64) The most common administrative division within a country.
(e.g., Province in Canada.)
sub_administrative_area varchar(64) The smallest administrative division within a country.
(e.g., County in Germany.)
building varchar(64) The descriptive name that identifies an individual location, if one exists.
dependent_locality varchar(64) If there is additional information about the locality it will be here.
(e.g., Neighborhood in Turkey.)
dependent_locality_name varchar(64) If the dependent_locality has a name, you'll find it here.
(e.g., The dependent_locality "Dong Cheng Qu" is named "Dong Cheng".)
double_dependent_locality varchar(64) If there is additional information about the dependent_locality you'll find it here.
(e.g., Village in the United Kingdom.)
locality varchar(64) Within a country, this is the most common population center.
(e.g., City in Chile.)
postal_code varchar(64) The complete postal code for the delivery point.
(e.g., V6G1V9 in Canada.)
postal_code_short varchar(64) Primary postal code information.
(e.g., 90210 in the United States.)
postal_code_extra varchar(64) Secondary postal code information.
(e.g., 3425 in the United States.)
premise varchar(64) Alphanumeric code pertaining to an individual location.
premise_extra varchar(64) Extra information about the premise that is not necessarily authoritative but might still be useful.
(e.g., In a French address, 25 bis rue Emile Zola, 91190 Gif Sur Yvette, France, the premise number could be followed by the word "bis" which would be considered premise_extra data.)
premise_number varchar(64) The alphanumeric component of the premise field.
(e.g., If premise contains "Plot 7/7A" premise_number would contain "7/7A".)
premise_type varchar(64) The premise type component of the premise field.
(e.g., If premise contains "Plot 7/7A" premise_type would contain "Plot".)
thoroughfare varchar(64) All thoroughfare components combined
thoroughfare_predirection varchar(64) The directional prefix component of the thoroughfare.
(e.g., If thoroughfare contains "N Main St" thoroughfare_predirection would contain "N".
thoroughfare_postdirection varchar(64) The directional suffix component of the thoroughfare.
(e.g., If thoroughfare contains "Main St N" thoroughfare_postdirection would contain "N".)
thoroughfare_name varchar(64) The name component of the thoroughfare.
(e.g., If thoroughfare contains "Main St" thoroughfare_name would contain "Main".)
thoroughfare_trailing_type varchar(64) The trailing thoroughfare type component of the thoroughfare.
(e.g., If thoroughfare contains "N Main St" thoroughfare_trailing_type would contain "St".)
thoroughfare_type varchar(64) The leading thoroughfare type component of the thoroughfare.
(e.g., If thoroughfare contains "Rue De La Gare" thoroughfare_leading_type would contain "Rue".)
dependent_thoroughfare varchar(64) All of the dependent thoroughfare components combined
dependent_thoroughfare_predirection varchar(64) The directional prefix component of the dependent_thoroughfare.
(e.g., If dependent_thoroughfare contains "N Main St" dependent_thoroughfare_predirection would contain "N".)
dependent_thoroughfare_postdirection varchar(64) The directional suffix component of the dependent_thoroughfare.
(e.g., If dependent_thoroughfare contains "Main St N" dependent_thoroughfare_postdirection would contain "N".)
dependent_thoroughfare_name varchar(64) The name component of the dependent_thoroughfare.
(e.g., If dependent_thoroughfare contains "N Main St" dependent_thoroughfare_name would contain "Main".)
dependent_thoroughfare_trailing_type varchar(64) The trailing dependent_thoroughfare type component of the dependent_thoroughfare.
(e.g., If dependent_thoroughfare contains "N Main St" dependent_thoroughfare_trailing_type would contain "St".)
dependent_thoroughfare_type varchar(64) The leading thoroughfare type component of the dependent_thoroughfare field.
(e.g., If dependent_thoroughfare contains "Rue De La Gare" dependent_thoroughfare_type would contain "Rue".)
building_leading_type varchar(64) The leading building type component of the building.
(e.g., If building contains "Bloc C" building_leading_type would contain "Bloc".)
building_name varchar(64) The name component of the building.
(e.g., If building contains "Westminster House" building_name would contain "Westminster".)
building_trailing_type varchar(64) The trailing building type component of the building.
(e.g., If building contains "Westminster House" building_trailing_type would contain "House".)
sub_building_type varchar(64) The leading sub-building type of the sub_building.
(e.g., If sub_building contains "Flat 1" sub_building_type would contain "Flat".)
sub_building_number varchar(64) The alphanumeric component of the sub_building.
(e.g., If sub_building contains "Flat 1" sub_building_number would contain "1".)
sub_building_name varchar(64) The descriptive name component of the sub_building.
(e.g., If sub_building contains "Basement Flat" sub_building_name would contain "Basement".)
sub_building varchar(64) All sub_building components combined.
post_box varchar(64) All post_box Post Office Box components combined
post_box_type varchar(64) The type component of the post_box.
(e.g., If post_box contains "PO Box 1234" post_box_type would contain "PO Box".)
post_box_number varchar(64) The alphanumeric component of the postbox.
(e.g., If post_box contains "PO Box 1234" post_box_number would contain "1234".)

Metadata

Field Name Type Definition
latitude decimal(9,6) The horizontal component used for geographic positioning; it is the angle between 0° (the equator) and ±90° (north or south) at the poles measured in decimal degrees. It is the first value in an ordered pair of latitude, longitude. A negative number denotes a location south of the equator; a positive number is north. Combining lat/lon values enables you to pinpoint addresses on a map.
longitude decimal(9,6 The vertical component used for geographic positioning; it is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward) measured in decimal degrees. It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/lon values enables you to pinpoint addresses on a map.
geocode_precision varchar(16) Indicates the precision of the latitude & longitude values.

None — Coordinates not known, possibly because address is invalid.

AdministrativeArea — Coordinate is only accurate down to the Administrative Area.
(e.g., typically a state or province)

Locality — Coordinate is only accurate down to the Locality level.
(e.g., typically a city or town)

Thoroughfare — Geocode is only accurate down to the Thoroughfare level.
(e.g., typically a street)

Premise — Geocode is accurate down to the premise level.
(e.g., typically an individual property or building)

DeliveryPoint — Geocode is accurate down to the actual delivery point.
(e.g., this is rooftop level)

Analysis

Field Name Type Definition
verification_status varchar(16) Indicates the verification status of the address.

None — Status not known, possibly because the address is invalid.
Partial — Parts of the address were verified.
Verified — The entire address was verified.
address_precision varchar(24) Indicates the precision of the address values.

None — Address not known, possibly because this address is invalid.

AdministrativeArea — Address is only verified down to the administrative area.
(e.g., typically a state or province)

Locality — Address is only verified down to the Locality.
(e.g., typically a city or town)

Thoroughfare — Address is only verified down to the Thoroughfare level.
(e.g., typically a street)

Premise — Address is verified down to the Premise level.
(e.g., typically an individual property or building)

DeliveryPoint — Address is verified down to the DeliveryPoint.
(e.g., this is rooftop level)

Supported Countries

The below countries are supported and available in our international address validation. Notice the verification and geocoding levels are different for each country. That means that addresses in Nicaragua, for example, can only be verified to the locality or city because that is the best data available for that country.

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

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff