Introduction:
Geocoder.us offers a free (for non-commercial use) web service that may be used to geocode physical addresses. The details of the service and usage terms may be located at: http://geocoder.us/. In general, the Geocoding service is based upon the use of Tiger/Line data gathered by the US Census bureau. Geocoding is defined as the process of estimating the latitude and longitude of a physical address. Naturally the service is based upon physical addresses so its use is limited to tagging physical addresses with a lat/long. Also, since this is based upon US Census Bureau data, only US addresses can be geocoded using the service.
This article will demonstrate the basics of submitting an address to the service, recovering and displaying the geocoded result, and will also demonstrate a simple approach to displaying the location as mapped using Yahoo maps.
The service can be used to obtain and store latitude and longitude on all of the addresses contained in some sort of contact database or asset location database, or might be useful for storing waypoints in a GPS navigation device.
The demonstration application will evoke the web service to find the coordinates for a physical address and will display the best result along with any other addresses that match the search criteria. In Figure 1, note that the search term, "100 Peachtree, Atlanta, GA" was sent to the service; the best result is displayed in the "Best Match" group and all matches are displayed in the "All Possible Matches" group box. Since "Peachtree" is a very common name for a street in Atlanta where it is apparently the civic pastime to name streets "Peachtree", the data grid view control contained in the "All Possible Matches" group is pretty full.
Figure 1: The demonstration application running
Figure 2: Displaying the coordinates in Yahoo Maps
Getting Started:
In order to get started, unzip the included project and open the solution in the Visual Studio 2005 environment. In the solution explorer, you should note these files (Figure 3) along with a web reference pointing to http://rpc.geocoder.us/dist/eg/clients/GeoCoder.wsdl
Figure 3: Solution Explorer
The Main Form (Form1.cs)
The main form is the only form contained in the application; all of the application specific code required to access the service, return the results of an address search, and to display those results as text or as a map are included in this class.
The code is pretty simple, if you'd care to open the code view up in the IDE you will see that the code file begins as follows:
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
The imports are per the default configuration for a Windows application.
Following the imports, the namespace and class are defined and a default constructor added.
namespace FreeAddressGeocoder
{
public partial class Form1 : Form
{
/// <summary>
/// Default constructor
/// </summary>
public Form1()
{
InitializeComponent();
}
Next up is the button click event handler used to evoke the Geocoding web service; the code is annotated to describe what is going on within the event handler.
/// <summary>
/// Geocode the address using the GeoCode Service
/// from geocoder.us
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnGeocode_Click(object sender, EventArgs e)
{
// make sure there is an address
// to geocode
if (txtSearchAddress.Text == string.Empty)
{
MessageBox.Show("Invalid search address.", "Error");
return;
}
try
{
// instance the geocoder service
us.geocoder.rpc.GeoCode_Service gcAddress = new us.geocoder.rpc.GeoCode_Service();
// the event handler for completion of the geocoding
// does the work of displaying the results; the site offers
// alternative methods for viewing the geocoding results
gcAddress.geocode_addressCompleted += new us.geocoder.rpc.geocode_addressCompletedEventHandler(GetLatLong);
// call the asynchronous version of the geocoder
gcAddress.geocode_addressAsync(txtSearchAddress.Text);
// dispose of the service instance
gcAddress.Dispose();
}
catch (Exception ex)
{
MessageBox.Show(ex.Message, "Geocoding Error");
}
}
}
The next section of the code is used to parse the results returned from the web service and to display the results to the user in the "Best Match" and "All Possible Matches" groups. The code is annotated to describe what each part of the code does.
/// <summary>
/// Get the geocoding service results and display them
/// to the user
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void GetLatLong(object sender, us.geocoder.rpc.geocode_addressCompletedEventArgs e)
{
try
{
// the address is broken up into parts so
// reassemble them into a street address using
// only the parts that have been populated
// by the service
// start with the street number
txtStreet.Text = e.Result[0].number.ToString() + " ";
// add the prefix (e.g., N, SE, etc.)
if (e.Result[0].prefix.ToString() != string.Empty)
txtStreet.Text += e.Result[0].prefix.ToString() + " ";
// add the street name
if (e.Result[0].street.ToString() != string.Empty)
txtStreet.Text += e.Result[0].street.ToString() + " ";
// add the suffix (if any)
if (e.Result[0].suffix.ToString() != string.Empty)
txtStreet.Text += e.Result[0].suffix.ToString() + " ";
//add the street type (e.g., ST, CT, RD, PKWY, etc.)
if (e.Result[0].type.ToString() != string.Empty)
txtStreet.Text += e.Result[0].type.ToString();
// add the city, state, and zip
txtCity.Text = e.Result[0].city.ToString();
txtState.Text = e.Result[0].state.ToString();
txtZip.Text = e.Result[0].zip.ToString();
// display the latitude and longitude
txtLatitude.Text = e.Result[0].lat.ToString();
txtLongitude.Text = e.Result[0][email protected]();
// create a datatable to hold any additional
// possible address matches
DataTable dt = new DataTable();
// define all of the columns and add them
// to the data table
DataColumn dcAddress = new DataColumn();
dcAddress.DataType = System.Type.GetType("System.String");
dcAddress.ColumnName = "Address";
dcAddress.Caption = "Address";
dt.Columns.Add(dcAddress);
DataColumn dcCity = new DataColumn();
dcCity.DataType = System.Type.GetType("System.String");
dcCity.ColumnName = "City";
dcCity.Caption = "City";
dt.Columns.Add(dcCity);
DataColumn dcState = new DataColumn();
dcState.DataType = System.Type.GetType("System.String");
dcState.ColumnName = "State";
dcState.Caption = "State";
dt.Columns.Add(dcState);
DataColumn dcZip = new DataColumn();
dcZip.DataType = System.Type.GetType("System.String");
dcZip.ColumnName = "Zip Code";
dcZip.Caption = "Zip";
dt.Columns.Add(dcZip);
DataColumn dcLat = new DataColumn();
dcLat.DataType = System.Type.GetType("System.String");
dcLat.ColumnName = "Latitude";
dcLat.Caption = "Lat";
dt.Columns.Add(dcLat);
DataColumn dcLong = new DataColumn();
dcLong.DataType = System.Type.GetType("System.String");
dcLong.ColumnName = "Longitude";
dcLong.Caption = "Lon";
dt.Columns.Add(dcLong);
// create a row
DataRow row;
// loop through all of the results and
// add each row to the data table for
// display in the All Possible Matches
// datagridview control
for (int i = 0; i < e.Result.Length; i++)
{
// create a new row
row = dt.NewRow();
// build a street address
string addr = e.Result[i].number.ToString() + " ";
if(e.Result[i].prefix.ToString() != string.Empty)addr += e.Result[0].prefix.ToString() + " ";
if (e.Result[i].street.ToString() != string.Empty)addr += e.Result[i].street.ToString() + " ";
if (e.Result[i].suffix.ToString() != string.Empty)addr += e.Result[i].suffix.ToString() + " ";
if (e.Result[i].type.ToString() != string.Empty)addr += e.Result[i].type.ToString();
// set the street address
row["Address"] = addr;
// set the city, state, and zip code
row["City"] = e.Result[i].city.ToString();
row["State"] = e.Result[i].state.ToString();
row["Zip Code"] = e.Result[i].zip.ToString();
// set the latitude and longitude
row["Latitude"] = e.Result[i].lat.ToString();
row["Longitude"] = e.Result[i][email protected]();
// add the new row to the table
dt.Rows.Add(row);
}
// configure and bind the grid to the table
dgvMatches.SelectionMode = DataGridViewSelectionMode.FullRowSelect;
dgvMatches.DataSource = dt;
dgvMatches.RowHeadersVisible = false;
dgvMatches.AutoSizeRowsMode = DataGridViewAutoSizeRowsMode.AllCells;
dgvMatches.ScrollBars = ScrollBars.Both;
dgvMatches.Refresh();
}
catch
{
MessageBox.Show("No matching address found", "Address");
}
}
The Exit button event handler is described in the next section; this code merely terminates the application.
/// <summary>
/// Exit the application
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnExit_Click(object sender, EventArgs e)
{
Application.Exit();
}
The last bit of code contained in the application is used open the Geocoded coordinates returned from the service into a running instance of Yahoo Maps. The approach here is simply to format a query string using the values returned from the service.
/// <summary>
/// Map the position using Yahoo! Maps if the user
/// double clicks on a row in the datagridview control
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void dgvMatches_DoubleClick(object sender, EventArgs e)
{
// map it on a double click
// get the lat and long from the selected row
string strLat = dgvMatches.SelectedRows[0].Cells[4].Value.ToString();
string strLon = dgvMatches.SelectedRows[0].Cells[5].Value.ToString();
// launch Internet Explorer and fill in the lat and
// long values url's argument list
System.Diagnostics.Process.Start("iexplore.exe","http://maps.yahoo.com/#mvt=m&lat=" + strLat +"&lon=" + strLon + "&mag=3&q1=" + strLat +"%2C%20" + strLon);
}
Summary
This application was provided as an example of how one might take advantage of the Geocoder.us Address Geocoding service. This service is free for non-commercial use. If one were required to geocode a collection of addresses yet lacked access to some of the available third party tools (such as the ESRI product line), this service could be invaluable. The service mentioned in this article is also capable of Geocoding road intersections which could also be very useful.