International Address Autocomplete API - reference
This page describes how to use the Smarty International Address Autocomplete API. (Free testing accounts available.)
Contents
- Overview
- HTTP request
- HTTP response
- 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 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+HEREHere 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 |
OR
| 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:
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.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. |
search | string | (empty) | The part of the address that has already been typed. Maximum character count is 32 characters. Required when Address ID is not specified in the URL. |
max_results | integer | 5 | Maximum number of address suggestions to return; range [1, 10]. |
max_group_results | integer | 100 | Maximum number of address suggestions to return when expanding address groups with an Address ID; range [1, 100]. |
geolocation | string | (empty) | Bias (prefer) results based on the location of the sender's IP address (IPv4 only). Valid value: onSupported countries: CAN, AUS, DEU. If the request to the API goes through a proxy, you will need to set an X-Forwarded-For header specifying the desired IP address for the request. |
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.
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 isn’t considered to be persistent. They are not to be stored and reused at a later time, as they’re only guaranteed to be valid for the duration 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 won’t be charged to your account.
The fields in these results are as follows:
entriesaddress_textaddress_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.
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:
streetlocalityadministrative_areaadministrative_area_shortadministrative_area_longpostal_codecountry_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": "1-123 Main St",
"locality": "Fredericton",
"administrative_area": "NB",
"administrative_area_short": "NB",
"administrative_area_long": "New Brunswick",
"postal_code": "E3A 1C7",
"country_iso3": "CAN"
}
]
}Supported character sets
By default, the character set returned will be the native set for that country. If any Latin characters are provided in the input (excluding numerics), the Latin character set will be returned.
- Cyrillic
- Greek
- Hebrew
- Kanji (Japanese)
- Simplified Chinese
- Arabic
- Thai
- Hangul (Korean)
Supported countries
Supports the following countries:
Country ISO3 Alpha-3
Country CodeAfghanistan AFG 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, Sint Eustatius, and Saba 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 Cabo 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 Democratic Republic of the Congo COD Cook Islands COK Costa Rica CRI Croatia HRV Cuba CUB Curaçao CUW Cyprus CYP Czechia CZE Ivory Coast 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 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 VAT Honduras HND Hong Kong HKG Hungary HUN Iceland ISL India IND Indonesia IDN Islamic Republic of Iran 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 Democratic People's Republic of Korea (North Korea) PRK Republic of Korea KOR Kosovo XKX 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 Republic of 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 Republic of Moldova 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 State of Palestine PSE Panama PAN Papua New Guinea PNG Paraguay PRY Peru PER Philippines PHL Pitcairn PCN Poland POL Portugal PRT Qatar QAT 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 MAF Saint Pierre and Miquelon SPM Saint Vincent and the Grenadines VCT Samoa WSM San Marino SMR São Tomé and Príncipe STP Saudi Arabia SAU Senegal SEN Serbia SRB Seychelles SYC Sierra Leone SLE Singapore SGP Sint Maarten (Dutch) 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 Islands SJM Sweden SWE Switzerland CHE Syrian Arab Republic SYR Taiwan TWN Tajikistan TJK United Republic of Tanzania TZA Thailand THA Timor-Leste TLS Togo TGO Tokelau TKL Tonga TON Trinidad and Tobago TTO Tunisia TUN Türkiye (Turkey) TUR Turkmenistan TKM Turks and Caicos Islands TCA Tuvalu TUV Uganda UGA Ukraine UKR United Arab Emirates ARE United Kingdom GBR Uruguay URY Uzbekistan UZB Vanuatu VUT Bolivarian Republic of Venezuela VEN Viet Nam VNM British Virgin Islands VGB Wallis and Futuna WLF Western Sahara ESH Yemen YEM Zambia ZMB Zimbabwe ZWE Åland Islands ALA
Subscription usage
Beyond ensuring that requests include proper authentication, clients of the International Address Autocomplete API must maintain an active API subscription.