International Address Autocomplete API

This page describes how to use the Smarty International Address Autocomplete API. (Free testing accounts available.)

Contents

1. Overview
   1. Features
   2. Example of Correct Implementation
2. HTTP Request
   1. URL Composition
   2. Request Methods
   3. Request Headers
   4. Input Fields
3. HTTP Response
   1. Status Codes and Results
   2. Example Response
4. Supplementary Material
   1. Supported Countries
   2. Subscription Usage
   3. SSL/TLS Information
   4. Try the Demo

Features

• Returns suggestions that are fully verified global addresses.
• Uses fuzzy logic during searching to:
  • Allow for missing directionals and street suffixes.
  • Allow substitution of street suffixes and unit designators. E.g., ST is accepted for AVE; APT is accepted for UNIT, etc.
  • Allow full or partial spelling of street suffixes and unit designators. E.g., ST can be spelled as STR or STREET and still match.
  • Filters allow for multiple cities or postal codes in a single country.

Note: Effective with the adoption of the V2 version of International Address Autocomplete, lookup usage will be based on the final selection of an address rather than per keystroke.

Example of Correct Implementation

Before reading through the detailed instructions for calling this API, it will probably be very helpful to see an example of a correct implementation of it in a user interface. Please go to this API demo page and experiment with the user interface there. In particular, observe how, when a base address has subunits, we show the user that there are subunits. And when the user clicks on a suggested address that includes subunits, we show the subunits to the user in a second drop-down menu.

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL (with line breaks for readability):

https://international-autocomplete.api.smarty.com/v2/lookup[/{address_id}]?
key=YOUR+EMBEDDED+KEY+HERE

Here is a more granular examination of the example above:

For additional information about URLs, please read our article about URL components.

HTTP Request: Supported Methods/Verbs

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests." Other common methods are PUT, POST, and DELETE which are not supported in this API.

The following methods are supported by this API:

• GET (for sending a single input)
• OPTIONS (for "pre-flight" cross-domain requests)

Note: When calling any of our address APIs using embedded key authentication, only the HTTP GET method is allowed.

Please note that all query string parameter values must be UTF-8 characters which are then url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. Common mistakes we see are non-encoded commas, semicolons, and pound signs. Pound signs (#) like in an apartment number (# 409), when properly encoded in a URL, become %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP Request: Headers

You must include the following required HTTP headers in all requests:

Input Fields

All input field parameters must be UTF-8 and then URL encoded.

Address ID in the URL

All summary results are returned with an address_id which allows you to get more details on known entries for that result.

You specify the address_id in the URL following the /v2/lookup path as in the following example. This should not be provided when the search parameter is used in the query string.

curl 'https://international-autocomplete.api.smarty.com/v2/lookup/PD4DPC8DPgNORk9MTQ?key=YOUR+EMBEDDED+KEY+HERE&country=FRA'

You must still specify a country and your authentication information in the query string. Additionally, the max_results parameter will be disregarded in order to provide more subunit results, up to the first 100 entries. If there are more than 100 entries, an additional summary result containing the rest of the entries will be returned as the 101st result.

HTTP Response: Status Codes and Results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Example Response

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice. In addition, the address_id returned in each result is not considered to be persistent. They are not to be stored and reused at a different time as they are only guaranteed to be valid within the life of a user session.

The resulting JSON from a query contains a candidates array of suggestions. There are two types of results you can receive depending on the query.

• Summary Results
• Detailed Results

Summary Results

curl 'https://international-autocomplete.api.smarty.com/v2/lookup?search=123+main&country=CAN&key=YOUR+EMBEDDED+KEY+HERE' -H 'referer: https://myneatwebsite.com'

These results are designed to be displayed in a dropdown select list allowing the user to continue typing to narrow the search. Calls of this type will not be charged to your account.

The fields in these results are as follows:

• entries
• address_text
• address_id

Here is an example of an actual response JSON based on the above query:

{
	"candidates": [
		{
			"entries": 12,
			"address_text": "123 Main St Winnipeg, MB, R3C",
			"address_id": "PD4DPC8DOjE4AzI9Uig2MTE2Lzo4UjI+NjEgLCtSTk1M"
		},
		{
			"entries": 5,
			"address_text": "123 Main St Ottawa, ON, K1S 1B9",
			"address_id": "PD4DPC8DOjE4AzAxUjArKz4oPlIyPjYxICwrUk5NTA"
		},
		{
			"entries": 1,
			"address_text": "123 Main St Fredericton, NB, E3A 1C6",
			"address_id": "PD4DPC8DPgNHRkxMTEhO"
		}
	]
}

The entries field indicates how many addresses are associated with the specific address_id.

When entries has a value greater than 1, it means that when you query again using the address_id in the URL, you will get results associated with that address_id, such as subunits (secondaries). These results will also be Summary Results, and you will receive the first 100 results. If there are more than 100 entries, an additional Summary Result will be returned containing the remaining entries.

When entries has a value of 1, it means that when you query again using the address_id in the URL you will receive a Detailed Result.

Detailed Results

curl 'https://international-autocomplete.api.smarty.com/v2/lookup/PD4DPC8DPgNHRkxMTEhO?country=CAN&key=YOUR+EMBEDDED+KEY+HERE' -H 'referer: https://myneatwebsite.com'

When you query using an address_id on a result where entries equals 1, you will receive a detailed result. Your account will be charged for each call of this type.

The fields in these results are as follows:

• street
• locality
• administrative_area
• postal_code
• country_iso3

...which you can use to fill form fields.

Depending on the country, some components may not be returned. Here is an example of an actual response JSON:

{
	"candidates": [
		{
			"street": "123 Main St",
			"locality": "Fredericton",
			"administrative_area": "NB",
			"postal_code": "E3A 1C6",
			"country_iso3": "CAN"
		}
	]
}

Supported Countries

• Supports the following 242 countries:

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

Subscription Usage

Beyond ensuring that requests include proper authentication, clients of the International Address Autocomplete API must maintain an active API subscription.

SSL/TLS Information

Use Modern Security Software and Cipher Suites