azsael / geocoding.net

C# GeoCoding / Address Validation API

#Generic C# Geocoding API

Includes a model and interface for communicating with five popular Geocoding providers. Current implementations include:

• Google Maps - docs
• Yahoo! BOSS Geo Services - docs
• Bing Maps (aka Virtual Earth) - docs
• ⚠️ MapQuest (Comercial API) - docs
• ⚠️ MapQuest (OpenStreetMap) - docs

The API returns latitude/longitude coordinates and normalized address information. This can be used to perform address validation, real time mapping of user-entered addresses, distance calculations, and much more.

See latest release notes.

⚠️ There are some open issues (#29, #45, #48) regarding MapQuest which have some workarounds. If you would like to help fix the issues, PRs are welcome.

##Installation

Install via nuget:

Install-Package Geocoding.net

Or download the latest release and add a reference to Geocoding.dll in your project.

##Example Usage

###Simple Example

IGeocoder geocoder = new GoogleGeocoder() { ApiKey = "this-is-my-optional-google-api-key" };
IEnumerable<Address> addresses = geocoder.Geocode("1600 pennsylvania ave washington dc");
Console.WriteLine("Formatted: " + addresses.First().FormattedAddress); //Formatted: 1600 Pennslyvania Avenue Northwest, Presiden'ts Park, Washington, DC 20500, USA
Console.WriteLine("Coordinates: " + addresses.First().Coordinates.Latitude + ", " + addresses.First().Coordinates.Longitude); //Coordinates: 38.8978378, -77.0365123

It can also be used to return address information from latitude/longitude coordinates (aka reverse geocoding):

IGeocoder geocoder = new YahooGeocoder("consumer-key", "consumer-secret");
IEnumerable<Address> addresses = geocoder.ReverseGeocode(38.8976777, -77.036517);

###Using Provider-Specific Data

GoogleGeocoder geocoder = new GoogleGeocoder();
IEnumerable<GoogleAddress> addresses = geocoder.Geocode("1600 pennsylvania ave washington dc");

var country = addresses.Where(a => !a.IsPartialMatch).Select(a => a[GoogleAddressType.Country]).First();
Console.WriteLine("Country: " + country.LongName + ", " + country.ShortName); //Country: United States, US

The Microsoft and Yahoo implementations each provide their own address class as well, BingAddress and YahooAddress.

###More Examples

A more in-depth runnable example of how this library can be integrated into an MVC4 application can be found in the latest release package. Download it and run locally.

##API Keys

Google allows anonymous access to it's API, but if you start hitting rate limits, you must sign up for a new Server API Key.

Bing requires an API key to access its service.

You will need a consumer secret and consumer key (PDF) for Yahoo.

MapQuest API requires a key. Sign up here: (http://developer.mapquest.com/web/products/open)

##How to Build from Source

Open in Visual Studio 2013 and build. It should automatically restore nuget package dependencies. If you get an error about a missing AssemblyVersion file, close the solution and reopen it and build again. The build depends on some .targets files that are downloaded from nuget. If the files aren't there when VS opens, it doesn't detect that they are there once nuget downloads them without a restart.

Service Tests

You will need to generate API keys for each respective service to run the service tests. Edit App.config in the Tests project and put in your API keys.