Configuring the plugin

The SmartyStreets website plugin is configured when it is initialized. Initialization occurs when jQuery.LiveAddress() is called. The plugin must be initialized before it can be used, and it should only be initialized once.

The copy-and-paste code on the installation page invokes the default initialization, using all the default settings and a website key from your account. Some basic customizations can be made during initialization.

Initialization

The code below shows one way you might initialize the plugin: by enabling debug mode, enabling the US and international APIs, and specifying a custom field mapping:

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script src="//d79i1fxsrar4t.cloudfront.net/jquery.liveaddress/3.2/jquery.liveaddress.min.js"></script>
<script>var liveaddress = $.LiveAddress({
	key: "YOUR_WEBSITE_KEY_HERE",
	debug: true,
	target: "US|INTERNATIONAL",
	addresses: [{
		address1: '#street-address',
		locality: '#city',
		administrative_area: '#state',
		postal_code: '#zip',
		country: '#country'
	}]
});
</script>

(The resulting liveaddress object provides some functions you can use.)

Configuration properties

DEPRECATED marks configuration options that are not supported past version 2.8 of the plugin. The most recent version is 3.0

Property Type Default Description
addresses array null An array of objects representing addresses, used to map fields. You will need to map fields manually. Possible fields to map include address1, address2, address3, address4, locality, administrative_area, postal_code, and country.
ambiguousMessage string "Matched multiple addresses.
Which did you mean?"
The message to display when an address is ambiguous. Keep it short.
autocomplete integer 10 (max) The number of suggestions to show while the user types in the street field. Set to 0 to disable autocomplete. Go to an example.

(Note: Address suggestions are not necessarily valid. Suggested addresses should still go through verification.)
autoMap
DEPRECATED
boolean true Whether to auto-map fields right away during initialization. Set to false if you plan on specifying your own field mapping later.
autoVerify boolean true Verify the address as soon as enough of it has been typed by the user. This will only happen once per address before the form is submitted to avoid annoying the user.
candidates integer 3 The number of matches to return when the address is ambiguous. If you set this to 1, all ambiguous addresses will appear to be perfectly valid instead.
certifyMessage string "Use as it is" The message to display where the user clicks to bypass verification and certify the address is correct.
changeMessage string "Go back" The message to display where the user clicks to go back to the form and edit their address.
cityFilter string "" Restricts autocomplete suggestions to just the specified cities. See city filtering for more info, or go to an example.
cityStatePreference string "" Whenever possible, the first three suggestions will be from these "preferred" cities/states. See preference for more info, or go to an example.
debug boolean false If enabled, debugging information and detailed logs will be printed to the console, and mapped fields will be highlighted and labeled. The submit button for each form that is mapped to the plugin is marked with green text. Use debug mode only for testing.
enforceVerification boolean false Removes the option for the user to "certify the address is correct" and bypass verification. This makes the form strict enough to disallow anyone from submitting the form without entering a valid address.
fieldSelector string "input[type=text], input:not([type]), textarea, select" The CSS selector which identifies input fields inside each form. Do not attempt to use this to map the form fields.
geocode boolean false Whether or not to request geocoded addresses from the international API.
geolocate boolean true Attempt to show autocomplete results in the user's city based on their IP address.
geolocatePrecision string "city" If the geolocate field is set to true then setting this field to city causes the geolocated results that bubble up to the top of the response to be from the city/state corresponding to the sender's IP address. Setting this field to state causes results from the sender's entire state to be preferred.
invalidCountryMessage string "Unknown country" The message to display when a country is invalid. Keep it short.
invalidMessage string "You entered an unknown address:" The message to display when an address is invalid. Keep it short.
key string "" Required. The website key for the web page on which the plugin is used. It must be in quotes.
missingInputMessage string "You didn't enter enough information" The message to display when an address is missing input in order to verify.
missingSecondaryMessage string "You forgot your apt/suite number or entered an unknown apt/suite number" The message to display when an address is missing a valid secondary number when verifySecondary is set to true.
noSuggestionsMessage string "No suggestions" The message to display when there are no autocomplete suggestions available for the provided user input.
requestUrl
DEPRECATED
string "https://
us-street.api.smartystreets.com
/street-address"
The URL to which API requests are made. You can change this to proxy requests through your own server, thus allowing you to hide your API key, monitor requests, and more, but it must act and look exactly like our actual endpoint.
requestUrlInternational string "https://
international-street.api.smartystreets.com
/verify"
The URL to which international API requests are made. You can change this to proxy requests through your own server, thus allowing you to hide your API key, monitor requests, and more, but it must act and look exactly like our actual endpoint.
requestUrlUS string "https://
us-street.api.smartystreets.com
/street-address"
The URL to which US API requests are made. You can change this to proxy requests through your own server, thus allowing you to hide your API key, monitor requests, and more, but it must act and look exactly like our actual endpoint.
stateFilter string "" Restricts autocomplete suggestions to the specified states. See state filtering for more info, or go to an example.
submitOnPause
DEPRECATED
boolean false This is an autocomplete enhancement. If the user has typed in an address of at least 10 characters and it comes up with no suggestions, after five seconds it will be submitted for verification. If valid, the address will appear in the autocomplete suggestion list. If this new suggestion is clicked on, the form is filled and marked as valid. Uses one lookup.
submitSelector string "[type=submit], [type=image], [type=button]:last" The CSS selector which identifies the submit button for your form. You don't usually need to set this yourself, but if you do, it's easiest to select by the button's ID. Go to an example.
submitVerify boolean true Verify addresses in a form when the form is submitted. If you set both this and autoVerify to false, no validation will occur automatically at all.
target string "US" The target API to submit the address to. To include the international API, set to "US|International". This is case insensitive, order insenstive, and whitespace insensitive. Possible inputs are "US", "US|international", and "International". Must be separated by a pipe.
timeout integer 5000 Milliseconds before an API request is considered to have failed if no response is received. (1000ms = 1s)
ui boolean true Whether to provide and execute the default UI for handling the address verification process, including autocomplete. Disable this to use your own. Only developers with experience using this plugin should disable its UI. We recommend using liveaddress.js instead.
verifySecondary boolean false If addresses are missing secondary numbers (e.g., apartment number, suite number) then the plugin will display the missingSecondaryMessage and allow the user to go back and change their address or accept the address as is. Go to an example.
waitForStreet boolean false Hides autocomplete suggestions until street information is entered. This is useful when using filters (geolocate, cityFilter, stateFilter, cityStatePreference) because filters only work once a street is entered. Can be used without filtering enabled as well. (Requires v2.7 or above.)

Next

That should be all you need to make it work. But if you want to do more, learn about the functions available to you after initializing the plugin. Also be sure to check out these stellar troubleshooting tips if you're experiencing problems.


Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff