This is an archived page. The information on this archived page is no longer current.

LiveAddress API with Javascript

API requests with Javascript

Making requests to LiveAddress via Javascript is easy: just follow the REST endpoint documentation. Let's look at a few ways to use LiveAddress API on your website.

Note: This code is presented as-is, and we are unable to help with specific implementations. However, you are welcome to contact us with bug reports, or you can submit a pull request on GitHub to suggest features, fixes, or changes.

For website forms

If your website has a form where users type their address (like shopping carts), you may be interested in our easy-peasy jQuery plugin which integrates with your website forms directly. Before a user is "allowed" to submit the form, the address must be verified or the user must certify their address is correct.

Our jQuery plugin is the recommended way to perform address validation on your website. It is powerful and customizable (if you're into that sort of thing), but also easy enough for anyone to start using without needing any scripting. If you're savvy and want something more lightweight, read on.

liveaddress .js — A non-jQuery wrapper

Our helper file, liveaddress .js, makes it super-easy to perform requests to LiveAddress via Javascript. No frameworks (jQuery, Prototype, etc.) are required, though they should be compatible and you may use one if you'd like.

Get liveaddress .js

liveaddress .js — For production websites, we recommend the minified version, liveaddress.min.js. To tinker with the code or fork the project, use the original, uncompressed version, liveaddress .js.

Add it to your webpage

Once you've downloaded the file, add a <script> tag to your HTML and then initialize it with your embedded key: <script type="text/javascript" src="liveaddress.min.js"></script> <script type="text/javascript">LiveAddress.init('1234567890123456789');</script> This usually goes in the <head> portion of the page, or just before the </body> tag. Replace 1234567890123456789 with your own HTML auth token. Remember to use the key that corresponds to the domain/host/IP address from which the request will be sent. You can find a listing of your keys and corresponding hosts in your account.

How to use it

Arguments

Each of these functions may accept, as input:

An object which maps fields to their values, according to allowed input parameters
A string, being the ID of a form element from which to obtain the address
A string, being the address to verify
An array of any of the above, for batch requests

The callback function will be invoked to handle the JSON response, which is passed in. The timeout callback will be invoked if the request times out, and is passed the original input. The timeout callback is entirely optional, but recommended.

Function reference

LiveAddress.verify( input , callback(json) [, timeoutCallback(input)] );

Performs a basic request to the API and returns its output. json contains the raw JSON response from the API. See the JSON structure.
LiveAddress.geocode( input , callback(results) [, timeoutCallback(input)] );

Geocodes an address. results contains an object like this:
```
{
	"coords": "36.05613, -115.10292"
	"lat": 36.05613
	"lon": -115.10292
	"precision": "Zip7"
}
```
LiveAddress.county( input , callback(county) [, timeoutCallback(input)] );

Obtains the county name of the address. county contains the county name as a string.

LiveAddress.components( input , callback(comp) [, timeoutCallback(input)]
			);

Parses a single-line (freeform) address into its individual components. comp contains an array of objects like this (empty response indicates invalid address):

[
	{
		city_name: "Las Vegas"
		delivery_point: "17"
		delivery_point_check_digit: "6"
		first_line: "3217 E Warm Springs Rd"
		last_line: "Las Vegas NV 89120-3157"
		plus4_code: "3157"
		primary_number: "3217"
		state_abbreviation: "NV"
		street_name: "Warm Springs"
		street_predirection: "E"
		street_suffix: "Rd"
		zipcode: "89120"
	}
]

Examples

Geocode an address

var addr = {
	street: "7584 E Big Canyon Dr.",
	zipcode: "92808"
};

LiveAddress.geocode(addr, function(geo) {
	alert("The address is at: " + geo.coords);
}, function(input) {
	alert("Oh no! Timed out. You supplied the street: " + input.street);
});

Parse a freeform address

LiveAddress.components("7584 big canyon anaheim, ca", function(comp) {
	var domElement = document.getElementByID("results");
	domElement.innerHTML = comp[0].first_line + "<br>" + comp[0].last_line;
});

Obtain county name

LiveAddress.county("address-textarea", function(county) {
	alert("The address is in " + county + " county.");
});

JSONP / Access-Control-Allow-Origin

Because of the same-origin policy implemented by most browsers, you may not perform POST requests or regular GET requests with Javascript to our API. In other words, you cannot use Javascript's XMLHttpRequest ("XHR") object to perform a request to our API.

There are two common workarounds for this.

JSONP

The usual way of circumventing this restriction is to perform what's known as a JSONP request. Because JSONP requests inject a <script> tag into the DOM containing the JSON response, the JSON string must be wrapped in a function call so the client-side can execute it and process the payload.

Using a Javascript framework like jQuery makes this really easy to do. Simply build a GET request with an extra parameter called callback, then execute it:
```
var url ="https://us-street.api.smartystreets.com/street-address?street=1600+Amphitheatre+Parkway&city=Mountain+View&state=CA&zipcode=94043&candidates=5&auth-token=<embedded key here>&callback=?";
$.getJSON(url, function(response) {
	console.log(response);
});
```
Also, note that HTTP status codes are irrelevant with JSONP requests; the only way to indicate failure is a timeout.

We also have a wrapper function to use LiveAddress with JSONP without the need for a framework, described above.
Server-side proxy

Another good idea, if you have the ability, is to perform a regular AJAX request to your server and have it make the request out to LiveAddress, then send the result back to the client. Because your server would be at your own domain name, you don't need to worry about JSONP.

Requests proxied through a server aren't hindered by the same-origin policy. This is beneficial if you have a large amount of addresses to process from a website and would like to verify up to 100 at a time. Bulk requests can only be done via POST, which JSONP cannot perform.