Most of the time, the plugin works fine out of the box. However, we've assembled this page over years of experience for those who are having difficulties.
You may also find it helpful to enable debug mode to peer inside the mind of the plugin.
Debug mode allows you to better see what's happening under the hood while you're developing, testing, or debugging the plugin on your site. To enable it, set
Check to make sure your mapping is correct. Help the plugin by properly telling it which input fields to attach to.
Great! Just make sure that the "text" attributes (what is displayed to the user in the
<option> tags) is either the full name of a state or the two-letter abbreviation. The "value" attributes of the
<option> tags can be anything you want. They can even be blank! If you do not enter a default value in the first
<option> tag then we will insert one for you. This enables autocomplete to work properly.
To function properly, those "text" attributes must match the full name of the state or the official, two-letter state abbreviations. Example: "California," "Iowa," "Maryland," etc. or "CA," "IA," "MD," etc. These can be all uppercase, all lowercase, or any combination of cases.
Note: State dropdowns only play well for US addresses. Using a state dropdown for other countries may or may not work properly. We recommend using a text field instead.
This is most likely because your website key is wrong or doesn't match the host/domain name exactly as shown by the URL in the browser. You must be viewing the page in a web browser using a host name like "localhost," an IP address, or a domain name. Going to "File" then "Open" in your browser will not work. Also, authorizing a website key for
mysite.com does not make it work on
www.mysite.com or any other subdomains of
mysite.com. For that you would need to use the wildcard character like
*.mysite.com would work for any subdomain of mysite.com
You can be sure there is a website key mismatch by opening your browser's dev tools and clicking on the "Network" tab and "Console" tab to monitor requests and errors. An error code of 401 means that your key and/or hostname is bad.
Ensure that the key you're using is allowed on the IP address, domain name, or other host name exactly as it is shown in the browser.
There are many reasons for this. In order to stay fast, address suggestions as you type are not guaranteed to be valid, nor do they come with ZIP Codes. Addresses must still go through the verification process. Autocomplete does not use any lookups against your account; lookups are only deducted from your balance when when the address is submitted for verification. Autocomplete suggestions are also not guaranteed to be in standardized format or cased properly.
Being a free service, the autocomplete service contains most—but not all—entries in its index. For example, only USPS-preferred city names are in the index, not nicknames like "St. Louis" where it should be "Saint Louis." Addresses, especially brand new addresses, can still be validated even if autocomplete has no suggestions for it. Further, LiveAddress can fix misspellings in user input and still validate the address on some occasions, whereas autocomplete will only suggest addresses matching what the user has typed.
Street names are required for filtering to occur. This is necessary to keep the autocomplete service fast. You can hide autocomplete results until a street name is entered by setting
true when configuring the plugin.
Make sure city names are spelled exactly correctly and have no punctuation. Make sure you're using the USPS-preferred city names. If you're filtering by state, make sure you're using the official two-letter state abbreviations only. Make sure there are no periods in the state abbreviations.
.verify(addressID) function by passing in the addressID of the form you want to manually verify.
index is the index of the address you are trying to access. Also, the
addressID is returned with the Address object when
.makeAddress(addressData) is called.
Yes! You need to be careful though. The plugin assumes an empty form so you need to notify it in some way that you are pre-filling the form. Here is an example of the recommended method using the jQuery
.change() method. The plugin is already set up to listen on that event so it works great.