International Address Autocomplete API

This page describes how to use the 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. Advanced Concepts
    1. Filtering
  5. Supplementary Material
    1. Subscription Usage
    2. SSL/TLS Information
    3. 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 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 131 countries:
    Country ISO3 Alpha-3
    Country Code
    Albania ALB
    Algeria DZA
    Andorra AND
    Angola AGO
    Argentina ARG
    Aruba ABW
    Australia AUS
    Austria AUT
    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
    Germany DEU
    Ghana GHA
    Greece GRC
    Guatemala GTM
    Guyana GUY
    Honduras HND
    Hong Kong HKG
    Hungary HUN
    Iceland ISL
    India IND
    Iraq IRQ
    Ireland IRL
    Israel ISR
    Italy ITA
    Jamaica JAM
    Japan JPN
    Jordan JOR
    Kenya KEN
    Korea (South) KOR
    Kosovo XKS
    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
    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
    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.smartystreets.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.smartystreets.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:

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: us-autocomplete-pro.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.
max_results integer 5 Maximum number of address suggestions to return; range [1, 10].
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.

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.smartystreets.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 components

  • street
  • locality
  • administrative_area
  • postal_code
  • country_iso3

...which you can use to fill form fields. Here's an example of the actual response JSON:


{
	"candidates": [
		{
			"street": "12TH AV",
			"locality": "OCEAN GROVE",
			"administrative_area": "VIC",
			"postal_code": "3226",
			"country_iso3": "AUS"
		},
		{
			"street": "TWELFTH AV",
			"locality": "EDEN PARK",
			"administrative_area": "VIC",
			"postal_code": "3757",
			"country_iso3": "AUS"
		},
		{
			"street": "TWELFTH AV",
			"locality": "ANGLESEA",
			"administrative_area": "VIC",
			"postal_code": "3230",
			"country_iso3": "AUS"
		},
		{
			"street": "TWELFTH AV",
			"locality": "CARLTON NORTH",
			"administrative_area": "VIC",
			"postal_code": "3054",
			"country_iso3": "AUS"
		},
		{
			"street": "TWELFTH AV",
			"locality": "RAYMOND ISLAND",
			"administrative_area": "VIC",
			"postal_code": "3880",
			"country_iso3": "AUS"
		}
	]
}

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

Sample Filter Strings:

  • include_only_administrative_area=Occitanie&include_only_locality=Arrouède
  • include_only_locality=Paris
  • include_only_postal_code=32140

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


The leader in location data intelligence

Ready to get started?