I’ve never been a fan of address forms that look like this;
From a data entry perspective, it forces users to hit TAB constantly. Furthermore, users who are less web savvy will transition between the mouse and the keyboard to negotiate these fields. It’s not a natural way to type an address.
By contrast, here is a human friendly address form:
While typing an address into this field, users can stay on the keyboard and simply type the address in a way that feels natural. The problem [for programmers] is parsing and validating this raw text once the form has been submitted.
Converting raw text to a valid address
Overcoming this challenge was part of a recent project. Thankfully, Google Maps does a great job of validating addresses. Google has made these validation & geocoding services through an API.
My plan was to tackle this challenge with the following 3 ingredients:
On paper, this appeared relatively straight-forward. However, in practice I encountered several hurdles. Below I’ve detailed how I overcame these hurdles.
Note: This is the 2nd version of this blog post. In my original blog post, I described how to use a server-side proxy service to relay results from Google’s geocode web service. Thor Mitchell, who is the Google Maps API product manager, posted a comment telling me that the proxy technique is unnecessarily difficult. In addition, this technique is against Google’s Terms of Service and vulnerable to quota exhaustion. The technique I describe below is in accordance best practices and the Terms of Service.
Creating the web form
To get started, I’ll create the simple web form shown in the screenshot above:
<form id="MyForm" name="MyForm" action="form.html">
<div id="map_canvas" style="float: right; height: 200px; width: 400px;"></div>
<div>
<label for="Name">Name</label>
<input id="Name" name="Name" type="text" />
</div>
<div>
<label for="FullAddress">Address</label>
<textarea id="FullAddress" name="FullAddress" cols="40" rows="5" class="fulladdressvalidator"></textarea>
</div>
<div>
<input id="Submit" name="Submit" value="Submit" type="button" />
</div>
</form>
Note, the Google Maps API Terms of Service requires that a map be displayed in conjunction with any Google Maps web services utilized. In other words, you are not allowed to geocode an address using the Google Maps API and not display a Google map. This is why I’ve included the map_canvas in the code above.
Creating an address jQuery Validator
Next, I’ll create a custom jQuery validator that performs the following tasks:
- Geocodes the address using the Google Maps API
- Return a true/false value indicating whether the address is valid
This seems simple, but it involves an asynchronous call to the Google Maps service. This means processing continues after the initial request is made. Before the result is received the validator needs to return a true/false value indicating whether the address is valid or not.
To overcome this challenge, I added an IsChecking flag using jQuery’s data method. This flag is set to true when the request is sent to the Google Maps API. When a form is submitted I’m able to check this flag to see whether the field has truly been validated.
Here is the code for this jQuery full address validator:
// FullAddress jQuery Validator
function FullAddressValidator(value, element, paras) {
// Convert the value variable into something a bit more descriptive
var CurrentAddress = value;
// If the address is blank, then this is for the required validator to deal with.
if (value.length == 0) {
return true;
}
// If we've already validated this address, then just return the previous result
if ($(element).data("LastAddressValidated") == CurrentAddress) {
return $(element).data("IsValid");
}
// We have a new address to validate, set the IsChecking flag to true and set the LastAddressValidated to the CurrentAddress
$(element).data("IsChecking", true);
$(element).data("LastAddressValidated", CurrentAddress);
// Google Maps doesn't like line-breaks, remove them
CurrentAddress = CurrentAddress.replace(/\n/g, "");
// Create a new Google geocoder
var geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': CurrentAddress }, function (results, status) {
// The code below only gets run after a successful Google service call has completed.
// Because this is an asynchronous call, the validator has already returned a 'true' result
// to supress an error message and then cancelled the form submission. The code below
// needs to fetch the true validation from the Google service and then re-execute the
// jQuery form validator to display the error message. Futhermore, if the form was
// being submitted, the code below needs to resume that submit.
// Google reported a valid geocoded address
if (status == google.maps.GeocoderStatus.OK) {
// Get the formatted Google result
var address = results[0].formatted_address;
// Count the commas in the fomatted address.
// This doesn't look great, but it helps us understand how specific the geocoded address
// is. For example, "CA" will geocde to "California, USA".
numCommas = address.match(/,/g).length;
// A full street address will have at least 3 commas. Alternate techniques involve
// fetching the address_components returned by Google Maps. That code looks even more ugly.
if (numCommas >= 3) {
// Replace the first comma found with a line-break
address = address.replace(/, /, "\n");
// Remove USA from the address (remove this, if this is important to you)
address = address.replace(/, USA$/, "");
// Check for the map_canvas, if it exists then position the Google Map
if ($("#map_canvas").exists()) {
$("#map_canvas").show();
Map("map_canvas", results[0].geometry.location);
}
// Set the textarea value to the geocoded address
$(element).val(address);
// Cache this latest result
$(element).data("LastAddressValidated", address);
// We have a valid geocoded address
$(element).data("IsValid", true);
} else {
// Google Maps was able to geocode the address, but it wasn't specific
// enough (not enough commas) to be a valid street address.
$(element).data("IsValid", false);
}
// Otherwise the address is invalid
} else {
$(element).data("IsValid", false);
}
// We're no longer in the midst of validating
$(element).data("IsChecking", false);
// Get the parent form element for this address field
var form = $(element).parents('form:first');
// This code is being run after the validation for this field,
// if the form was being submitted before this validtor was
// called then we need to re-submit the form.
if ($(element).data("SubmitForm") == true) {
form.submit();
} else {
// Re-validate this property so we can return the result.
form.validate().element(element);
}
});
// The FullAddress validator always returns 'true' when initially called.
// The true result will be return later by the geocode function (above)
return true;
}
// Define a new jQuery Validator method
$.validator.addMethod("fulladdress", FullAddressValidator);
Putting it all together
The steps above describe how to:
- Geocode addresses using the Google Maps API
- Create a custom jQuery Validator to use Google Maps API for address validation
The final step is to combine all of these pieces into a working form. Below is the completed client-side code for the form shown above.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title>Example Form </title>
<link href="./css/site.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.microsoft.com/ajax/jquery.validate/1.7/jquery.validate.min.js"></script>
<script src="http://maps.google.com/maps/api/js?sensor=false" type="text/javascript"></script>
</head>
<body>
<div class="page">
<div id="main">
<form id="MyForm" name="MyForm" action="form.html">
<div id="map_canvas" style="float: right; height: 200px; width: 400px;"></div>
<div>
<label for="Name">
Name</label>
<input id="Name" name="Name" type="text" />
</div>
<div>
<label for="FullAddress">
Address</label>
<textarea id="FullAddress" name="FullAddress" cols="40" rows="5" class="fulladdressvalidator"></textarea>
</div>
<div>
<input id="Submit" name="Submit" value="Submit" type="button" />
</div>
</form>
</div>
</div>
<script type="text/javascript">
// The following code show execute only after the page is fully loaded
$(document).ready(function () {
if ($('#MyForm').exists()) {
// Enable jQuery Validation for the form
$("#MyForm").validate({ onkeyup: false });
// Add validation rules to the FullAddress field
$("#FullAddress").rules("add", {
fulladdress: true,
required: true,
messages: {
fulladdress: "Google cannot locate this address."
}
});
// This function will be executed when the form is submitted
function FormSubmit() {
$.submitForm = true;
if (!$('#MyForm').valid()) {
return false;
} else {
if ($("#FullAddress").data("IsChecking") == true) {
$("#FullAddress").data("SubmitForm", true);
return false;
}
alert('Form Valid! Submit!');
// return true; // Uncomment to submit the form.
return false; // Supress the form submission for test purpose.
}
}
// Attach the FormSubmit function to the Submit button
if ($('#Submit').exists()) {
$("#Submit").click(FormSubmit);
}
// Execute the ForumSubmit function when the form is submitted
$('#MyForm').submit(FormSubmit);
}
});
// Create a jQuery exists method
jQuery.fn.exists = function () { return jQuery(this).length > 0; }
// Position the Google Map
function Map(elementId, geolocation) {
var myOptions = {
zoom: 13,
mapTypeId: google.maps.MapTypeId.ROADMAP
}
var map = new google.maps.Map(document.getElementById(elementId), myOptions);
map.setCenter(geolocation);
}
// FullAddress jQuery Validator
function FullAddressValidator(value, element, paras) {
// Convert the value variable into something a bit more descriptive
var CurrentAddress = value;
// If the address is blank, then this is for the required validator to deal with.
if (value.length == 0) {
return true;
}
// If we've already validated this address, then just return the previous result
if ($(element).data("LastAddressValidated") == CurrentAddress) {
return $(element).data("IsValid");
}
// We have a new address to validate, set the IsChecking flag to true and set the LastAddressValidated to the CurrentAddress
$(element).data("IsChecking", true);
$(element).data("LastAddressValidated", CurrentAddress);
// Google Maps doesn't like line-breaks, remove them
CurrentAddress = CurrentAddress.replace(/\n/g, "");
// Create a new Google geocoder
var geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': CurrentAddress }, function (results, status) {
// The code below only gets run after a successful Google service call has completed.
// Because this is an asynchronous call, the validator has already returned a 'true' result
// to supress an error message and then cancelled the form submission. The code below
// needs to fetch the true validation from the Google service and then re-execute the
// jQuery form validator to display the error message. Futhermore, if the form was
// being submitted, the code below needs to resume that submit.
// Google reported a valid geocoded address
if (status == google.maps.GeocoderStatus.OK) {
// Get the formatted Google result
var address = results[0].formatted_address;
// Count the commas in the fomatted address.
// This doesn't look great, but it helps us understand how specific the geocoded address
// is. For example, "CA" will geocde to "California, USA".
numCommas = address.match(/,/g).length;
// A full street address will have at least 3 commas. Alternate techniques involve
// fetching the address_components returned by Google Maps. That code looks even more ugly.
if (numCommas >= 3) {
// Replace the first comma found with a line-break
address = address.replace(/, /, "\n");
// Remove USA from the address (remove this, if this is important to you)
address = address.replace(/, USA$/, "");
// Check for the map_canvas, if it exists then position the Google Map
if ($("#map_canvas").exists()) {
$("#map_canvas").show();
Map("map_canvas", results[0].geometry.location);
}
// Set the textarea value to the geocoded address
$(element).val(address);
// Cache this latest result
$(element).data("LastAddressValidated", address);
// We have a valid geocoded address
$(element).data("IsValid", true);
} else {
// Google Maps was able to geocode the address, but it wasn't specific
// enough (not enough commas) to be a valid street address.
$(element).data("IsValid", false);
}
// Otherwise the address is invalid
} else {
$(element).data("IsValid", false);
}
// We're no longer in the midst of validating
$(element).data("IsChecking", false);
// Get the parent form element for this address field
var form = $(element).parents('form:first');
// This code is being run after the validation for this field,
// if the form was being submitted before this validtor was
// called then we need to re-submit the form.
if ($(element).data("SubmitForm") == true) {
form.submit();
} else {
// Re-validate this property so we can return the result.
form.validate().element(element);
}
});
// The FullAddress validator always returns 'true' when initially called.
// The true result will be return later by the geocode function (above)
return true;
}
// Define a new jQuery Validator method
$.validator.addMethod("fulladdress", FullAddressValidator);
</script>
</body>
</html>
All this work, just so I can do this:
