Address Autocompletion Example

This is an example showing how web application developers can incorporate the power of the BC Physical Address Geocoder service into their application easily, including advanced auto-complete functionality.

Result:

Documentation

This address auto-completion example makes use of jQuery UI's "autocomplete" function. The following stylesheet and scripts must be included in order to use jQuery UI:

<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.10.1/themes/smoothness/jquery-ui.css" />
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.1/jquery.min.js"></script>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.10.1/jquery-ui.min.js"></script>

Next you must include a text input field on your page, which you will use for geocoding with auto-completion:

<input type="text" id="geocodeField" placeholder="Type an address" />

Then you tell jQuery to perform auto-completion on this field, and provide it a function which will return a list of potential auto-completions for a given input, as well as a function to call when one of the suggestions is selected. Below, "geocodeSuggest" uses a jQuery ajax call to obtain the potential address matches from the geocoder REST API. An in-line function takes the selected suggestion and displays the selection's details in formatted JSON text in the result box.

// Geocode Address autocomplete
$('#geocodeField').autocomplete({
	minLength: 3,
	source: geocodeSuggest,
	select: function(evt, ui) {
		$('#output').text(JSON.stringify(ui.item.data, null, 4));
	}
});

// function for suggesting geocode autocompletion options
function geocodeSuggest(request, response, options) {
	var params = {
		minScore: 50,
		maxResults: 5,
		echo: 'false',
		brief: true,
		autoComplete: true,
		addressString: request.term
	};
	$.extend(params, options);
	$.ajax({
		url: gcApi + "addresses.json",
		data: params,
		success: function(data) {
			var list = [];
			if(data.features && data.features.length > 0) {
				list = data.features.map( function(item) {
					return {
						value: item.properties.fullAddress,
						data: item
					}
				});
			}
			response(list);
		},
		error: function() {
			response([]);
		}
	});
}

For further information on jQuery UI's Autocomplete function, see the jQuery Documentation.

There are various options available, set using the "params" variable in the geocodeSuggest function. Here is a description of the options which can be used to configure the results returned by the REST API ad address auto-completion suggestions:

autocomplete

With autocomplete='true', the geocoder allows for the last word of input to be only partially input, trying to automatically complete is as would be expected. When autocomplete='false', the geocoder expects a complete address to be input and only allows for minor spelling mistakes or typos; this is good for validating complete addresses but will not provide as good of a user experience when used for auto-completion.

brief

when brief='true', significantly fewer result attributes are returned for each match, reducing the data transfer overhead of the autocomplete process.

echo

If echo is set to true, site name and unit number details will be echoed back as part of the results even if they are not actually matched.

maxResults

This specifies the maximum number of results to show in the drop-down list while the user is typing.

minScore

This specifies the minimum score of results to return. Any results with a score less than the specified minimum will not be returned.

outputSRS

This specifies the Spatial Reference System to use for the output coordinates, using standard EPSG codes. The list of acceptable code is specified here.

setBack

This specifies the distance from the street curb to set back the returned point, in meters. By default the returned point is intended to be located on the curb.

interpolation

This specifies the allowable method of interpolation. By default, "adaptive" interpolation is used. Alternatively, "linear" or "none" can be specified.

locationDescriptor

This specifies the type of location point to return, one of "any", "accessPoint", "frontDoorPoint", "parcelPoint", "rooftopPoint", or "routingPoint".

bbox

This specifies a bounding box to filter the results, specified as "minx,miny,maxx,maxy" in the output-SRS coordinate system.

centre

This specifies the centre point of a distance filter, specified as "x,y" in the output-SRS coordinate system. Must also use data-distance.

maxDistance

This specifies the maximum distance from the centre point which results may be, in meters, relative to the point specified by "centre".

localities

This specifies a list of locality names which results must be in one of. The list must be comma-delimited and must contain exact spellings of locality names and so is not generally suitable for user input.

localitiesNot

This specifies a list of locality names which results must not be in. The list must be comma-delimited and must contain exact spellings of locality names and so is not generally suitable for user input.

matchPrecision

This specifies a list of MatchPrecision values which results must have one of. The list must be comma-delimited and may contain any of the MatchPrecision values: "occupant", "unit", "site", "civic_number", "intersection", "block", "street", "locality", "province"

matchPrecisionNot

This specifies a list of MatchPrecision values which results must have none of. The list must be comma-delimited and may contain any of the MatchPrecision values: "occupant", "unit", "site", "civic_number", "intersection", "block", "street", "locality", "province"

For more information on these geocoder parameters, see the REST API Console