International Address Autocomplete API (deprecated)

ATTENTION: This documentation is for a deprecated International Autocomplete API that will no longer receive updates. Support for this API will be discontinued on February 13, 2024. Please migrate to the new International Autocomplete API for continued service and improved features.

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

Features
1. Features
HTTP request
HTTP response
1. Status codes and results
2. Example response
Advanced concepts
1. Filtering
Supplementary material

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 secondary designators. E.g., ST is accepted for AVE; APT is accepted for UNIT, etc.
Allow full or partial spelling of street suffixes and secondary designators. E.g., ST can be spelled as STR or STREET and still match.

Filters and preferences allow for multiple cities in a single country.
Allows searching on alternate cities.

Supports the following 137 countries:

Country	ISO3 Alpha-3 Country Code
Albania	`ALB`
Algeria	`DZA`
Andorra	`AND`
Angola	`AGO`
Argentina	`ARG`
Aruba	`ABW`
Australia	`AUS`
Austria	`AUT`
Azerbaijan	`AZE`
Bahamas	`BHS`
Bahrain	`BHR`
Barbados	`BRB`
Belarus	`BLR`
Belgium	`BEL`
Belize	`BLZ`
Benin	`BEN`
Bermuda	`BMU`
Bolivia	`BOL`
Bosnia and Herzegovina	`BIH`
Botswana	`BWA`
Brazil	`BRA`
Brunei Darussalam	`BRN`
Bulgaria	`BGR`
Burkina Faso	`BFA`
Burundi	`BDI`
Cameroon	`CMR`
Canada	`CAN`
Chile	`CHL`
China	`CHN`
Colombia	`COL`
Congo-Brazzaville	`COG`
Congo-Kinshasa	`COD`
Costa-Rica	`CRI`
Croatia	`HRV`
Cuba	`CUB`
Cyprus	`CYP`
Czech Republic	`CZE`
Denmark	`DNK`
Dominican Republic	`DOM`
Ecuador	`ECU`
Egypt	`EGY`
El Salvador	`SLV`
Estonia	`EST`
Finland	`FIN`
France	`FRA`
Gabon	`GAB`
Georgia	`GEO`
Germany	`DEU`
Ghana	`GHA`
Greece	`GRC`
Guatemala	`GTM`
Guyana	`GUY`
Honduras	`HND`
Hong Kong	`HKG`
Hungary	`HUN`
Iceland	`ISL`
India	`IND`
Indonesia	`IDN`
Iraq	`IRQ`
Ireland	`IRL`
Israel	`ISR`
Italy	`ITA`
Jamaica	`JAM`
Japan	`JPN`
Jordan	`JOR`
Kazakhstan	`KAZ`
Kenya	`KEN`
Korea (South)	`KOR`
Kosovo	`XKX`
Kuwait	`KWT`
Latvia	`LVA`
Lebanon	`LBN`
Lesotho	`LSO`
Liechtenstein (Territory CHE)	`LIE`
Lithuania	`LTU`
Luxembourg	`LUX`
Macau	`MAC`
Macedonia	`MKD`
Malawi	`MWI`
Malaysia	`MYS`
Mali	`MLI`
Malta	`MLT`
Mauritania	`MRT`
Mauritius	`MUS`
Mexico	`MEX`
Montenegro	`MNE`
Morocco	`MAR`
Mozambique	`MOZ`
Namibia	`NAM`
Netherlands	`NLD`
New Zealand	`NZL`
Nicaragua	`NIC`
Niger	`NER`
Nigeria	`NGA`
Norway	`NOR`
Oman	`OMN`
Panama	`PAN`
Paraguay	`PRY`
Peru	`PER`
Philippines	`PHL`
Poland	`POL`
Portugal	`PRT`
Qatar	`QAT`
Romania	`ROU`
Russia	`RUS`
Rwanda	`RWA`
Saint Kitts and Nevis	`KNA`
Saudi Arabia	`SAU`
Senegal	`SEN`
Serbia	`SRB`
Singapore	`SGP`
Slovakia	`SVK`
Slovenia	`SVN`
South Africa	`ZAF`
Spain	`ESP`
Suriname	`SUR`
Swaziland	`SWZ`
Sweden	`SWE`
Switzerland, Liechtenstein	`CHE`
Taiwan	`TWN`
Tajikistan	`TJK`
Tanzania	`TZA`
Thailand	`THA`
Togo	`TGO`
Trinidad and Tobago	`TTO`
Tunisia	`TUN`
Turkey	`TUR`
Uganda	`UGA`
Ukraine	`UKR`
United Arab Emirates	`ARE`
United Kingdom	`GBR`
Uruguay	`URY`
Venezuela	`VEN`
Viet Nam	`VNM`
Yemen	`YEM`
Zambia	`ZMB`
Zimbabwe	`ZWE`

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/lookup?
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	`/lookup`
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.

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:

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.smartystreets.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.
`search`	string	(empty)	Required. The part of the address that has already been typed. Maximum length is 128 bytes.
`max_results`	integer	`5`	Maximum number of address suggestions to return; range [1, 10].
`distance`	integer	`5`	When using `geolocation=geocodes`, and `latitude/longitude`, this field specifies the radius in MILES from the geocode point.
`geolocation`	string	(empty)	Use the client's IP address to limit results to the surrounding area. The possible options are: `adminarea` - Limit results to the client's administrative area (state, province, etc.). `locality` - Limit results to the client's locality (city). `postalcode` - Limit results to the postal code where the client's IP address is registered. `geocodes` - Limit results to an area surrounding the lat/lon where the user's IP address is registered. See also `distance`. See filtering for more information.
`include_only_administrative_area`	string	(empty)	Limit the results to only the administrative area provided. An administrative area is like a state in the United States, a province in Canada, or region in France. Please use the correct postal name for the administrative area (e.g. use "NSW" instead of "New South Wales"). Example: `NSW` See filtering for more information.
`include_only_locality`	string	(empty)	Limit the results to only the locality provided. A locality is a significant population center (i.e. city, town, or village). Example: `Paris` See filtering for more information.
`include_only_postal_code`	string	(empty)	Limit the results to only the postal code provided. When this parameter is used, no `include_only_administrative_area` and/or `include_only_locality` parameters can be used. Example: `29200` See filtering for more information.
`latitude`	string	(empty)	Limit the results to the surrounding area specified by latitude and longitude. See also `distance` Example: `-2.0234` This must be used with the longitude parameter. See filtering for more information.
`longitude`	string	(empty)	Limit the results to the surrounding area specified by latitude and longitude. See also `distance` Example: `44.0234` This must be used with the latitude parameter. See filtering for more information.

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

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.

curl 'https://international-autocomplete.api.smarty.com/lookup?key=YOUR+EMBEDDED+KEY+HERE&search=Louis&country=FRA&include_only_locality=Paris' -H 'referer: https://myneatwebsite.com'

The resulting JSON contains a candidates array of suggestions consisting of the following possible components

street
locality
administrative_area
sub_administrative_area
super_administrative_area
postal_code
country_iso3

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

Depending on the country, some components may not be returned. For example, sub_administrative_area and super_administrative_area components are only applicable in certain countries. Here is an example of an actual response JSON:


	{
		"candidates": [
		{
			"street": "De Blikken 1",
			"locality": "Oostburg",
			"administrative_area": "Zeeland",
			"sub_administrative_area": "Sluis",
			"postal_code": "4501 AC",
			"country_iso3": "NLD"
		},
		{
			"street": "Veerhoeklaan 5",
			"locality": "Oostburg",
			"administrative_area": "Zeeland",
			"sub_administrative_area": "Sluis",
			"postal_code": "4501 AE",
			"country_iso3": "NLD"
		},
		{
			"street": "Zuidzandsestraat 103",
			"locality": "Oostburg",
			"administrative_area": "Zeeland",
			"sub_administrative_area": "Sluis",
			"postal_code": "4501 AN",
			"country_iso3": "NLD"
		},
		{
			"street": "Pastoor Van Genklaan 2",
			"locality": "Oostburg",
			"administrative_area": "Zeeland",
			"sub_administrative_area": "Sluis",
			"postal_code": "4501 AH",
			"country_iso3": "NLD"
		},
		{
			"street": "Pastoor Van Genklaan 2",
			"locality": "Oostburg",
			"administrative_area": "Zeeland",
			"sub_administrative_area": "Sluis",
			"postal_code": "4501 AJ",
			"country_iso3": "NLD"
		}]
		}

Filtering

To limit autocomplete suggestions to a locality and/or administrative_area or postal code, you can use filters expressed in the include_ parameters.

Important filter rules and limitations:

The geolocation value MUST only be those specified in the parameter documentation. It maps a user's IP address to a location and automatically includes that location in the include_only fields below. When using this field, you may not use any of the other filtering fields discussed below.
The include_only_administrative_area value MUST only be the official postal name for the administrative area within the designated country. Partial values will not work.
The include_only_locality value MUST only be the official postal name for the locality within the designated country. Partial values will not work.
The include_only_postal_code value MUST only be the entire postal code for the designated country. Partial values will not work.
include_only_administrative_area and include_only_locality fields MAY be used separately or together. Only one of each may be specified.
include_only_postal_code field CANNOT be used with any other include_only_administrative_area or include_only_locality fields.
latitude field must be used with the longitude field and CANNOT be used with any other filtering fields. See also distance
longitude field must be used with the latitude field and CANNOT be used with any other filtering fields. See also distance

Sample filter strings:

geolocation=locality
include_only_administrative_area=Occitanie&include_only_locality=Arrouède
include_only_locality=Paris
include_only_postal_code=32140
latitude=-2.32678&longitude=44.25834&distance=20

SSL/TLS information

Use modern security software and Cipher Suites

International Address Autocomplete API (deprecated)

Contents

Features

HTTP request: URL composition

HTTP Request: Supported Methods/Verbs

HTTP request: Headers

Input fields

HTTP Response: Status Codes and Results

Example response

Filtering

Important filter rules and limitations:

Sample filter strings:

SSL/TLS information

Ready to get started?

Products

Solutions

Developer Hub

Library

Company