Documentation

 

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/3.2.1/jquery.min.js"></script>
<script src="//d79i1fxsrar4t.cloudfront.net/jquery.liveaddress/3.4/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

PropertyTypeDefaultDescription
addressesarraynullAn 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.
ambiguousMessagestring"Matched multiple addresses.
Which did you mean?"
The message to display when an address is ambiguous. Keep it short.
autocompleteinteger10 (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: Because the US Autocomplete API relies on the user to know their primary number, the returned suggestions do not necessarily represent valid addresses. These suggestions contain the house number provided as well as a valid street+city+state. Submitting those values to the US Street API will provide the fully validated address if one exists.
autoMap DEPRECATEDbooleantrueWhether to auto-map fields right away during initialization. Set to false if you plan on specifying your own field mapping later.
autoVerifybooleantrueVerify 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.
candidatesinteger3The 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.
certifyMessagestring"Use as it is"The message to display where the user clicks to bypass verification and certify the address is correct.
changeMessagestring"Go back"The message to display where the user clicks to go back to the form and edit their address.
cityFilterstring""Restricts autocomplete suggestions to just the specified cities. See city filtering for more info, or go to an example.
cityStatePreferencestring""Whenever possible, the first three suggestions will be from these "preferred" cities/states. See preference for more info, or go to an example.
debugbooleanfalseIf 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.
enforceVerificationbooleanfalseRemoves 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.
fieldSelectorstring"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.
geocodebooleanfalseWhether or not to request geocoded addresses from the international API.
geolocatebooleantrueAttempt to show autocomplete results in the user's city based on their IP address.
geolocatePrecisionstring"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.
invalidCountryMessagestring"Unknown country"The message to display when a country is invalid. Keep it short.
invalidMessagestring"You entered an unknown address:"The message to display when an address is invalid. Keep it short.
keystring""Required. The website key for the web page on which the plugin is used. It must be in quotes.
missingInputMessagestring"You didn't enter enough information"The message to display when an address is missing input in order to verify.
missingSecondaryMessagestring"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.
noSuggestionsMessagestring"No suggestions"The message to display when there are no autocomplete suggestions available for the provided user input.
requestUrl DEPRECATEDstring"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.
requestUrlInternationalstring"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.
requestUrlUSstring"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.
stateFilterstring""Restricts autocomplete suggestions to the specified states. See state filtering for more info, or go to an example.
submitOnPause DEPRECATEDbooleanfalseThis 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.
submitSelectorstring"[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.
submitVerifybooleantrueVerify 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.
targetstring"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.
timeoutinteger5000Milliseconds before an API request is considered to have failed if no response is received. (1000ms = 1s)
uibooleantrueWhether 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.
verifySecondarybooleanfalseIf 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.
waitForStreetbooleanfalseHides 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.