GeoNames .NET WCF Client

Introduction

GeoNames is a geographical database available under a Creative Commons attribution license. This data is accessible free of charge through a number (30+) of Web services.

The Web services include direct and reverse geocoding, finding places through postal codes, finding places next to a given place, weather observations for a given location, and finding Wikipedia articles about neighbouring places, etc.

Background

I have recently been working with the GeoNames services, both from JavaScript and from .NET. Among other things, we have been working with postal code auto-completion on the Web using JavaScript, and server-side postal code validation using .NET.

All these cool GeoNames services could definitely be used in many different contexts and applications. I have some ideas myself of UI controls and widgets that I would like to develop using GeoNames as data provider.

Therefore, I developed this WCF client for accessing the GeoNames services from .NET in a uniform, easy object-oriented manner.

Using the Code

These are just a few C# examples of using the client.

All the services are available through a single class, the GeoNamesClient (inherits System.ServiceModel.ClientBase<T>). We first create an instance of this object:

  using ( GeoNamesClient client = new GeoNamesClient ( ) )
  {
    ...
  }

Once the GeoNamesClient is created, any service may be called through this object. The first example shows how to retrieve all the cities within a geographical bounding box:

  double north = 44.1, south = -9.9, east = -22.4, west = 55.2;
  var cities = client.GetCities ( north, south, east, west );
  foreach ( GeoCity city in cities )
  {
    // GeoCity has many more properties to choose from...
    Console.WriteLine ( "City, Name={0}, Population={1}", city.Name, city.Population );
  }

The next example shows how to find weather observation for a given location:

  double latitude = 42, longitude = -2;
  var response = client.FindNearbyWeather ( latitude, longitude );
  GeoWeatherObservation weather = response.WeatherObservation;

  // GeoWeatherObservation has many more properties to choose from...
  Console.WriteLine ( "Current temperature is {0} degrees
    (delivered from the {1} weather station)",
    weather.Temperature, weather.StationName );

The client also provides overloaded methods for specifying culture, service verbosity, and controlling the max number of records to return for each service. The example shows how to search any geographical toponym that matches "london," with Spanish culture settings (place names, etc.) and limit the number of returned results to 10:

  GeoToponymSearchCriteria criteria = new GeoToponymSearchCriteria ( );
  criteria.Query = "london";
  criteria.Culture = "es";
  criteria.MaxRows = 10;
  var response = client.SearchToponyms ( criteria );
  foreach ( GeoToponym toponym in response )
  {
    // GeoToponym has many more properties to choose from...
    Console.WriteLine ( "Found toponym match, name:{0}", toponym.Name );
  }

Updated: Added support for geocoding addresses. This new example shows geocoding an address to determine it's spatial coordinate, and then pass coordinate to FindNearbyPostalCodes in order to find nearby postal codes for this address:

  string address = "1600 Amphitheatre Parkway Mountain View, CA  94043";
  double latitude, longitude;
  if ( client.TryGeocode ( address, out latitude, out longitude ) )
  {
    var response = client.FindNearbyPostalCodes ( latitude, longitude, 10 );

    foreach ( GeoPostalCode code in response )
    {
      ...
    }
  }
  else
    Console.WriteLine ( "-- Geocoding failed --" );

2.0.0.0 Update: Added support for approximating the bounding box for a given latitude/longitude pair, and a given radius in kilometers. The formula is based on the WGS84 system. A new useful GetBoundingBox method has been added to the GeoNamesClient class. This method could be used in conjunction with IGeoNamesClient methods that take bounding boxes, such as the GetCities method(s).

Below is an example of using GetBoundingBox to get a bounding box from a latitude/longitude pair and a radius, and then pass the bounding box to the GetCities method to retrieve cities within this bounding box:

double lat = 23.854, lng = 5.78;
double radius = 100; // kilometers
double north, south, east, west;

client.GetBoundingBox ( lat, lng, radius,
  out north, out south, out east, out west );

var cities = client.GetCities ( north, south, east, west );
foreach ( GeoCity city in cities )
{
  ...
}

Conclusion

If you need to access GeoNames services from your .NET application, you might want to look into my client. It supports all the available services, through a nice, object-oriented API.

History

2008-11-02 1.0.0.0
2008-11-04 1.5.0.0 Added support for geocoding
2009-04-17 2.0.0.0
- added support for WGS84 bounding box calculation (read updated article)
- fixed Distance property serialization error, by changing type to String. The data returned in the Distance property is actually a String and not a Double; it is already formatted based on the specified return culture. Sorry for any existing code I might break..
- fixed mapping to GeoStreetSegment.FeatureClasses, now mapped to MAF/TIGER Feature Class Codes
- fixed/resolved failing tests