International Address Autocomplete API

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

Contents

  1. Features
    1. Features
  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.

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:

URL Components Values Notes
Scheme https Non-secure http requests are not supported.
Hostname international-autocomplete.api.smarty.com
Path /v2/lookup
Address ID The Address ID is used to get further information about a particular result. This value will be supplied by a previous call to the API. This parameter should not be supplied when the search query parameter is used. See Address ID in the URL for usage information.
Query String ?key=YOUR+EMBEDDED+KEY+HERE

OR

?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE
You may use either "embedded key" or "secret key" authentication. Remember to be careful how you use "secret key" authentication. See our authentication documentation. Additional query string parameters are introduced in the next section.

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:

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:

Header Description Example
Host The Host request header field specifies the internet host and port number of the resource being requested. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically. Host: international-autocomplete.api.smarty.com
Referer The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser or programming language HTTP libraries will add this header automatically. However, some interfaces such as cURL do not, so you may need to add it manually. Referer: https://mycoolwebsite.com

Input Fields

Name Type Default Value Description
country string (empty) Required. The ISO3 Alpha-3 country code where the desired address is located. Only uppercase values are allowed. See supported country codes. Maximum length is 3 bytes.
max_results integer 5 Maximum number of address suggestions to return; range [1, 10].
include_only_locality string (empty) Limit the results to only the localities provided. A locality is a significant population center (i.e. city, town, or village). When this parameter is used, include_only_postal_code cannot be used. Separate multiple values with a comma.
Example: Paris,Versailles
include_only_postal_code string (empty) Limit the results to only the postal codes provided. When this parameter is used, include_only_locality cannot be used. Separate multiple values with a comma.
Example: 29200,29201

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.

Status Code Response and Explanation
401 Unauthorized: The embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.
402 Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400 Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.
422 Unprocessable Entity (Unsuitable parameters): Returns errors describing what needs to be corrected.
429 Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. You can avoid this error by adding your IP address as an authorized host for the embedded key in question.
200 OK (success!): The response body is a JSON object with a suggestions array containing suggestions based on the supplied input parameters.

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

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
    Kosovo XKV
    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


Ready to get started?