Generic C# Geocoding API

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

• Google Maps - Google geocoding docs
• Yahoo! BOSS Geo Services - Yahoo PlaceFinder docs
• Bing Maps (aka Virtual Earth) - Bing geocoding docs
• ⚠️ MapQuest (Commercial API) - MapQuest geocoding docs
• ⚠️ MapQuest (OpenStreetMap) - MapQuest OpenStreetMap geocoding docs
• HERE Maps - HERE developer documentation

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 is a potential issue (#29) regarding MapQuest that has a workaround. If you would like to help fix the issue, PRs are welcome.

Installation

Install via nuget:

Install-Package Geocoding.Core

and then choose which provider you want to install (or install all of them):

Install-Package Geocoding.Google
Install-Package Geocoding.MapQuest
Install-Package Geocoding.Microsoft
Install-Package Geocoding.Yahoo
Install-Package Geocoding.Here

Example Usage

Simple Example

IGeocoder geocoder = new GoogleGeocoder() { ApiKey = "this-is-my-google-api-key" };
IEnumerable<Address> addresses = await geocoder.GeocodeAsync("1600 pennsylvania ave washington dc");
Console.WriteLine("Formatted: " + addresses.First().FormattedAddress); //Formatted: 1600 Pennsylvania Ave SE, Washington, DC 20003, USA
Console.WriteLine("Coordinates: " + addresses.First().Coordinates.Latitude + ", " + addresses.First().Coordinates.Longitude); //Coordinates: 38.8791981, -76.9818437

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 = await geocoder.ReverseGeocodeAsync(38.8976777, -77.036517);

Using Provider-Specific Data

GoogleGeocoder geocoder = new GoogleGeocoder();
IEnumerable<GoogleAddress> addresses = await geocoder.GeocodeAsync("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.

API Keys

Google can use a Server API Key, and some environments now require one to access the service reliably.

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)

HERE requires an app ID and app Code

How to Build from Source

dotnet restore
dotnet build

For a nice experience, use Visual Studio Code to work with the project. The editor is cross platform and open source.

Alternatively, if you are on Windows, you can open the solution in Visual Studio and build.

Service Tests

You will need to generate API keys for each respective service to run the service tests. Make a settings-override.json as a copy of settings.json in the test project and put in your API keys. Then you should be able to run the tests.

Most provider-backed integration tests skip with a message indicating which setting is required when credentials are missing. The Yahoo suite is still explicitly skipped while issue #27 remains open, but it now uses the same credential checks when those tests are re-enabled.

Sample App

The sample app in samples/Example.Web is an ASP.NET Core 10 minimal API that can geocode and reverse geocode against any configured provider.

dotnet run --project samples/Example.Web/Example.Web.csproj

Configure a provider in samples/Example.Web/appsettings.json or via environment variables such as Providers__Google__ApiKey. Once the app is running, use samples/Example.Web/sample.http to call /providers, /geocode, and /reverse.