Plugin functions

This plugin is deprecated and will receive no continued development.

After initializing the plugin, a variety of functions are available to you in the returned object.

On this page

• Functions
• Mapping fields
• Address objects
• Response objects

Functions

.activate(addressID)

"Turns on" an address identified by addressID (given during mapping) so that it will be verified when the form is submitted or the address changes. Usually called sometime after deactivate is called.

.autoVerify([newSetting])

Pass in true or false to turn autoVerify on or off, respectively. Pass in nothing to simply return the current setting. See more about autoVerify here.

.deactivate([addressID])

"Turns off" an address identified by addressID (given during mapping) so it won't be verified when it changes or when the form is submitted. This "soft" deactivation can be reversed by calling activate with the appropriate addressID. If nothing is passed in, this deactivates the plugin entirely. (Mapped addresses, address IDs, etc. are destroyed.) This is a "hard" deactivation. Reactivating the entire plugin requires either remapping using the mapFields function or reinstantiating the plugin. This function is useful for web pages that have dynamic forms that are sometimes visible and sometimes not. See an example here.

.getMappedAddressByID(addressID)

Returns an Address object with specified addressID (given during mapping) that is mapped to a form. This function is mostly used internally by the plugin itself, but it can be used if the user needs to manipulate the address in some custom way.

.getMappedAddresses()

Returns an array of Address objects that are mapped to forms. Similar purpose as getMappedAddressByID. Mostly for internal purposes.

.makeAddress(addressData)

Returns a new Address object. addressData should be a string containing the entire address or an object mapping fields to values. For instance: liveaddress.makeAddress({ street: "123 Main St", city: "Schenectady", state: "New York", zipcode: "12345" });. Addresses constructed in this manner are independent of any mapped fields. You won't usually need this.

.mapFields([map])

Maps form fields to the type of data they contain. Specify your own field mapping with CSS selectors. Pass in nothing to use the mapping from initialization or your own field mapping to use that. Overwrites any existing mapping. Can be useful for dynamic forms.

.on(eventName, callback)

Similar to jQuery's on function, this is specifically for binding your own handlers to our plugin's custom events. The benefit of using this on function instead of jQuery's is that your handler will be fired first instead of last. See the events documentation for more information and examples. Make sure to call previousHandler(event, data); in order for the normal plugin functionality to still occur after you intercept the event.

.setCityFilter(cities)

Changes the city filter for autocomplete suggestions. cities should be a list of city names, separated by commas.

.setCityStatePreference(preferred)

Changes the preference for autocomplete suggestions. preferred should be a list of city and state pairs where the city and state are separated by a comma and each pair is separated by a semicolon.

.setKey(key)

Changes the website key used to authenticate requests. Seldom used outside of certain debugging scenarios or maybe in private-labeling situations.

.setStateFilter(states)

Changes the state filter for autocomplete suggestions. states should be a list of state names, separated by commas.

.verify(address | addressID[, callback(response)])

Performs a request to the API given an input address and invokes the callback, giving it a Response object. address can be a string (containing a single-line address) or an object where keys are fields and values are the address data. (Do not use an actual Address object.) Instead of an address, you can provide an addressID. You can use this function to programmatically click the "Verify" button. This function is asynchronous and does not return a value. If you are considering using this function to simply verify an address, we recommend making calls to our US Street Address API or International Street Address API instead.

Mapping fields

Set up the plugin by specifying field mapping. A contrived example that maps two addresses, one using all available fields and another using just one field, is shown below:

$.LiveAddress({
	key: 'YOUR_WEBSITE_KEY_HERE',
	addresses: [{
		id: 'billing',		// IDs are not part of the address
		address1: '#street1',
		address2: '#street2',	// Not all these fields are required
		locality: '#city',
		administrative_area: '#state',
		postal_code: '#zip',
		country: '#country'
	},
	{
		id: 'shipping',		// IDs are optional, but can be helpful
		freeform: '#entireAddress',
		country: '#country2'
	}]
});

This example shows a field mapping during initialization, but you can pass the same kind of array into the mapFields function.

Notice that we specify fields using CSS selectors. It's usually easiest to give your fields an ID and then use the CSS ID selector (the # symbol) to express the specific DOM elements to bind to. All mapped fields must be inside a <form> tag; no exceptions.

Mandatory fields (US target)

address1 + locality + administrative_area

address1 + postal_code

freeform

Mandatory fields (International target)

address1 + locality + administrative_area + country

address1 + postal_code + country

freeform + country

Table of Fields

Name	Description
id	The ID that you set to identify the address.
address1	The first line of the address.
address2	The second line of the address.
address3	The third line of the address.
address4	The fourth line of the address.
locality	The locality or city.
administrative_area	The administrative area or state.
postal_code	The postal code or ZIP Code.
country	The country.
freeform	The freeform field. This is used when the entire address is on one line. Used in place of a address1 + locality + adminstrative_area combination. Must be used with the country mapping field when dealing with international addresses.
match	The match field. See more here.

Address object

Address objects represent input (un-verified) addresses. They are obtained by calling makeAddress or are received by argument in an event handler.

Properties

• active

  If true, the address is activated. If false, the address is deactivated. See the activate and deactivate functions for more information.

• form

  The form object that the address is mapped to. Multiple addresses can be associated with a single form, but usually it is just one.

• lastField

  The last input field that is associated with the address. Usually is the ZIP Code, but can be the city/state/zip (last line), street (freeform), or country fields depending on your form.

• lastStreetInput

  The value of what is typed in the input field mapped as the street value. Used for autocomplete to detect changes.

• verifyCount

  The number of times that the address has been verified.

Table of functions

Function	Description
.abort(event [,keepAccept])	Resets an address, so to speak, so that it can be run through the verification process again from the beginning. This is often used in your own event handlers when you want to abort the verification process. Pass in the event to make sure it stops firing other handlers. This function will automatically "un-accept" the address. If you want the address to stay "accepted" for some reason, set the second argument to true. See events.
.accept([data, showVerified])	Marks the address as "accepted" (whether it was verified or not). Forms won't submit until every address is accepted. If intervening with an event handler, pass through the data to the next event. By default, calling this will turn the status indicator green. Set the second argument to false to prevent that.
.countryISO()	Returns the 3-digit ISO code that corresponds to the country associated with the address.
.enoughInput()	Returns true if the address has enough data to be submitted for verification, false otherwise. This check is done implicitly during verification anyway. If verification is invoked and this is true, the user will be notified of which input is missing.
.get(field)	Gets the value stored within the address by field name, such as "address1," "postal_code," etc. See US output fields and international output fields.
.getDomFields()	Returns an associative array (an object) which contains references to the DOM elements for the fields in the address, if there are any.
.hasDomFields()	Returns true if the address has DOM elements associated with any of its fields.
.id()	Returns the unique ID associated with this Address object.
.isDomestic()	Returns true if the address is detected to be in the United States; false otherwise.
.isFreeform()	Returns true if the address is considered to be a freeform (or "single-line") address, where all the data is contained in the "freeform" field and country in the "country" field. Returns false otherwise.
.replaceWith( replacement[, updateDomElement, event])	Replaces the values in the address with those found in replacement, which is an object returned from the API. (The API's raw response is an array of JSON objects; pass in just one of those objects. If an array of objects is passed in, the first object is used.) Set updateDomElement to true to update any DOM element values associated with the address, and event can be the event which initiated the request.
.set(field, value[, updateDomElement, keepState, sourceEvent]	Sets the value of field in the address to value. If updateDomElement is true, the value of the field on the DOM (if there is one) will be updated. If keepState is true, the state of the address ("changed" or "accepted") will not be changed. sourceEvent may be an event object which caused this change to happen.
.status()	Gets the state of the address, whether it is "changed" or "accepted."
.undo( [updateDomElement])	For each field in the address, switches the current value with the previous value. If the argument is true or undefined, the value of the DOM element associated with each field (if any) will be updated to reflect the change.
.verify([callback])	Invokes verification on this address. Supply an optional callback function to which the Response will be passed if the request succeeds. If you supply a callback, events will stop firing for this verification process once a response is received; it will be up to your callback to handle the response after that point. (The address is not automatically updated to reflect the verification results.)
.toRequestInternational()	Returns an object mapping fields to values, ready to submit to the international API. Use this to "convert" the address object to a format accepted by the international API.
.toRequestUS()	Returns an object mapping fields to values, ready to submit to the US API. Use this to "convert" the address object to a format accepted by the US API.
.toString()	Returns a string representation of the values for each field of the address (separated by spaces).
.unaccept()	Marks the address as "changed" (thus, not accepted) and raises the associated event.

Response object

Response objects are obtained by calling verify or are received by argument to an event handler. They contain the raw output of the API and some helpful wrapper functions to make the output easier to interpret and use.

Properties

• length

  The number of raw elements.

• raw

  The raw output from the API. This will always be an array of matching candidates. Use this property to access data about particular candidates returned from the API. For example: response.raw[0].metadata.latitude

Table of functions

All the following functions return true/false and may optionally be passed an index from 0 to n-1, where n is the number of candidates returned. If no index is passed in, then 0 is assumed.

Function	Description
.isInvalid()	The address is considered invalid (only one candidate returned).
.isValid()	The address is considered valid (only one candidate returned).
.isAmbiguous()	The address is considered ambiguous (more than one candidate returned).
.isMissingSecondary()	The address is valid, but is missing a secondary (unit/apartment/suite) number.

Having trouble?

Take a look at these troubleshooting tips we put together with lots of love.