« Previous Chapter 1: Mapping    Back to Index    Next Chapter 2: Mapping and Geocoding »

Chapter 2: Geocoding and Reverse-Geocoding

This chapter gives you a short introduction in geocoding and reverse-geocoding. Geocoding is important, if you want to get the coordinate for a specified address. After the address is geocoded, the coordinate can be used for map positioning. The map requires meter coordinates for correct positioning. Further, the geocoder client supports reverse geocoding which can be used to find possible addresses for a specified coordinate.

2.1 Geocode an address phrase

Lets start with our first geocoding example. Fill out the input fields below and press the geocode button. After receiving the response from the geocoder server, the example displays a list of possible coordinates for the entered address.

Geocoding example 2a Source code example 2a: 
	<!DOCTYPE html>

<html>
	<head>
		<title>Chapter 2: Geocoding example 2a</title>
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>	
		<script type="text/javascript">
			var geocoder;
			IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
			{
				if (event.name == 'geocoding') {
					//(2) initialize geocoder client
					geocoder = new IWGeocoderClient();
					IWEventManager.addListener(geocoder, 'ongeocode', function(event)
					{
						//call method to handle results 
						return showGeocodingResults(event);
					});
			
					function showGeocodingResults(event) // callback method
					{
						var results = event.results;
								
						if (results.length > 0)
						{
							var iwGeocodingResult = results[i];
							//handle geocoding results ...
						}
					}
			
					//function to start geocoding
					function doGeocoding(inputAddress, countryCode, maximumHits)
					{
						geocoder.geocodeAddressString(inputAddress, countryCode, maximumHits);
					}
				}
			});
	
			//(1) load geocoding module
			IWLoader.loadModules(['geocoding']);
		</script>
	</head>
	<body>
		<form id="geocodeForm" action="">
			//...
		</form>
	</body>
</html>

The previous source code is an extract of example 2a and shows the core functionality of geocoding. It looks a little bit more complex than our first mapping example. The reason is, that we have to handle the server response by ourselves. But a closer look at the code will show, that using the API for geocoding is also very easy. Let us take the code apart and have a look what it does.

2.1.1 load geocoding module and listen on module load

To use geocoding functions you need to load the module 'geocoding' with following code line: 
IWLoader.loadModules(['geocoding']);

If a module is completely loaded the event 'onmoduleload' is fired.

2.1.2 initialize geocoder client

If the module 'geocoding' is loaded, you can initialize geocoder client.

At first we need a new geocoder client, so we instantiate the IWGeocoderClient class. Then we add a new listener to the IWEventManager object. With the IWEventManager we can add so called "event listeners". Listeners can be used to determine when a request comes in. In this case, we catch the geocoding event 'ongeocode' and call the showGeocodingResults() method to display the result after the geocoder server has sent an answer. 

var geocoder = new IWGeocoderClient();
IWEventManager.addListener(geocoder, 'ongeocode', function(event) { return showGeocodingResults(event); });

2.1.3 Calling the geocodeAddressString method

We define two javascript methods, doGeocoding() and showGeocodingResults(). In doGeocoding() we just forward the values from the HTML form to the geocoder server by calling the geocodeAddressString method. The second parameter has to be a country code. This is necessary, because the address search would by to complex without localizing it to a country. In our example we want to search in Germany. 

function doGeocoding(inputAddress, countryCode, maximumHits)
{					
	geocoder.geocodeAddressString(inputAddress, countryCode, maximumHits);
}

The complete list of supported country codes is specified in the configration file of your geocoder server. The following table shows only some example codes.

Code Country Code Country
D Deutschland A Österreich
CH Schweiz B Belgien
NL Niederlande F Frankreich
E Spanien L Luxemburg
I Italien GB Großbritannien
N Norwegen DK Dänemark
S Schweden P Portugal
AND Andorra RSM San Marino
FIN Finnland PL Polen
CZ Tschechien IRL Irland
GRC Griechenland HUN Ungarn
SVK Slowakei ALB Albanien
BIH Bosnien-Herzegowina HRV Kroatien
MDA Moldawien ROU Rumänien
SRB Serbien SVN Slowenien
MNE Montenegro BGR Bulgarien
BLR Weißrussland EST Estland
LTU Litauen LVA Lettland
MKD Makedonien MLT Malta
RUS Russland TUR Türkei
UKR Ukraine UAE Vereinigte Arabische Emirate

The server will now process our geocoding request and will send an answer back to the geocoder client. The answer will then be caught by our event listener and delegated to the showGeocodingResults() method. The method handles the result from the geocoder server and writes it for example into a table. For this, the method gets as parameter theevent object from the geocoder client. We know that this event is an instance of IWGeocodingEvent, so we grab the geocoding results from the results attribute. The results attribute contains an array of IWGeocodingResult objects. We can now iterate over all results and can access the geocoded address by calling the getAddress() method. An address has methods to return a short (toFormattedString) or full (toFullFormattedString) string representation. We use the getter methods from the address object to create a formatted address string.

The first example shows you a simple way to geocode a free address search. This is very powerful feature but in some cases it is necessary for you to set the address attributes explicit. The following example uses an IWAddress object for setting this attributes. You can set the street, house number, zipcode, city and countrycode attribute. The structure of the next example is very similar to our first, so we explain only the main different part.

Geocoding example 2b

2.2.1 Calling the geocodeAddress method

The doGeocoding() method gets now all address attributes from the HTML form separately. The only thing that we must do is to create an IWAddress object and set its properties. After this, we can call the geocodeAddress() method which takes the address object as parameter. The geocoding event is also caught by the event listener and automatically forwarded to the showGeocodingResult() method which prints the geocoding result in the table. 

function doGeocoding(street, houseNumber, zipCode, city, countryCode, maximumHits)
{					
	var address = new IWAddress();
	address.setStreet(street);
	address.setHouseNumber(houseNumber);
	address.setZipCode(zipCode);
	address.setCity(city);
	address.setCountryCode(countryCode);
				
	geocoder.geocodeAddress(address, maximumHits);
}

2.3 Search addresses within a specified radius

The following reverse geocoding examples demonstrates the use of the reverse geocoding methods. The examples are very similar to the previous examples at the top of the page.

Reverse-Geocoding example 2c Source code example 2c: 
<!DOCTYPE html>

<html>
	<head>
		<title>Chapter 2: Reverse-Geocoding example 2c</title>
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
	
		<script type="text/javascript">
			var geocoder;
	
			IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
			{
				if (event.name == 'geocoding') {
					geocoder = new IWGeocoderClient();
					IWEventManager.addListener(geocoder, 'onreversegeocode', function(event)
					{
						//call method to handle results 
						return showReverseGeocodingResults(event);
					});
					
					function showReverseGeocodingResults(event) // callback method
					{
						var results = event.results;
								
						if (results.length > 0)
						{
							
							var iwGeocodingResult = results[i];
							var address = event.results[i].getAddress();
							//handle reverse geocoding results
						}
					}
				}
			});
			
			IWLoader.loadModules(['geocoding']);
			
			function doReverseGeocoding(projection, x, y, radius)
			{
				geocoder.reverseGeocodeByRadius(new IWCoordinate(x, y, projection), radius);
			}
	</script>
</head>
<body>
		<form id="geocodeForm" action="">
			//...
		</form>
	</body>
</html>

2.4 Search a minimum amount of addresses

The difference between to the first and the second reverse geocoding example is, that we call in the first the reverseGeocodeByRadius method from the geocoder client and in the second the reverseGeocodeByHits method.

Reverse-Geocoding example 2d

   « Previous Chapter 1: Mapping    Back to Index    Next Chapter 2: Mapping and Geocoding »

Copyright Sat Apr 20 14:07:01 CEST 2024 infoware GmbH