📄 README.md

A C# library for connecing to Geocodio (https://geocod.io/), a geocoding service covering the United States and Canada.

Carrier cough Version 2.0 of cSharpGeocodio has arrived!

For those using previous versions, version 2.0 has some substantial changes so it will probably break a few things.

What is geocoding? Per Wiki (https://en.wikipedia.org/wiki/Geocoding):

Geocoding is the process of taking input text, such as an address or the name of a place, and returning a latitude/longitude location on the Earth's surface for that place. Reverse geocoding, on the other hand, converts geographic coordinates to a description of a location, usually the name of a place or an addressable location.

A human readable address turns into a point (latitude and longitude) on the Earth's surface, a process known as forward geocoding. A point of latitude and longitude turns into a human readable address, a process known as reverse geocoding. Trust the process.

Why, my good comrade, could this be useful? Maybe you want to know the distance between Las Vegas and Mackinaw City if you were to walk in a direct path along the Earth's surface. You could reverse geocode the two cities and then use the pair of latitude and longitude corrdinates to calculate the distance. There are many applications for the information provided through the geocoding process. Uber and Lyft and Waze and Google Maps could not work without it.

Some code examples are below. We can perform individual geocoding operations or send batches.

Create a client and a field settings object

c#
//First paramater is our API key, second is the client type we wish to create.
//Geocodio offers a special HIPAA endpoint when needing to geocodio sensitive information.  See their website for additional details.
var client = new GeoCoderV2("your_api_key", ApiClientType.RegularApi);

//Generate the fields settings object to use with our request.
//Geocodio lets you query additional fields such as Census tract or Congressional district.
//We can specify whether to query all of the fields or none of them.  Inidividual fields can be set on or off after creation
//The default is false, so we use true here to turn them all on and query everything!
var fields = GeocodioDataFieldSettings.CreateDataFieldSettings(true);

//Do not query for 2010 Census information
fields["census2010"] = false;
%%CODEBLOCK0%%c#
//Forward geocode a single address
var forwardGeocodoResults = await client.ForwardGeocodeAsync("3850 S Las Vegas Blvd, Las Vegas, NV 89109", fields);

//Forward geocode a batch of addresses
var someAddresses = new List<string>();
someAddresses.Add("3850 S Las Vegas Blvd, Las Vegas, NV 89109");
someAddresses.Add("2801 Westwood Dr, Las Vegas, NV 89109");
someAddresses.Add("1352 Rufina Cir, Santa Fe, NM 87507");

var batchforwardGeocodoResults = await client.ForwardGeocodeAsync(someAddresses, fields);

//Get the coordinates.  ForwardGeocodeAsync returns the same type whether single or batch geocoding.
//The GeoCodeInfo item in forwardGeocodoResults.Results[0].Response.Results[0] conains a lot of additional information.
//Any results in forwardGeocodoResults.Results[0].Response.Results[0] are ordered most accurate to least
var latitude = forwardGeocodoResults.Results[0].Response.Results[0].Location.Latitude;
var longitude = forwardGeocodoResults.Results[0].Response.Results[0].Location.Longitude;
%%CODEBLOCK1%%c#
//Reverse geocode a single point
var reverseGeocodoResults = await client.ReverseGeocodeAsync("39.362136, -74.418693", fields);

//Reverse geocode a batch of points
var someCoordinates = new List<string>();
someCoordinates.Add("39.362136, -74.418693");
someCoordinates.Add("43.080726, -70.740992");
someCoordinates.Add("37.264944, -115.816437");

var batchReverseGeocodoResults = await client.ReverseGeocodeAsync(someCoordinates, fields);

//Get the address.  ReverseGeocodeAsync returns the same type whether single or batch geocoding.
//The GeoCodeInfo item in reverseGeocodoResults.Results[0].Response.Results[0] conains a lot of additional information.
//Any results in reverseGeocodoResults.Results[0].Response.Results[0] are ordered most accurate to least
var address = reverseGeocodoResults.Results[0].Response.Results[0].FormattedAddress;
%%CODEBLOCK2%%c#
//Indexer syntax:
fields["census2010"] = true;
fields["census2015"] = false;
//Method syntax:
fields.SetFieldQueryStatus("census2011", true);
fields.SetFieldQueryStatus("acs-economics", true)

//We can also check the status of fields.
var toBeQueried = fields.GetFieldQueryStatus("census2011");

//Exception will be thrown, because census1939 is not a valid Geocodio data field key.
var toBeQueried_Exception = fields.GetFieldQueryStatus("census1939");
%%CODEBLOCK3%%c#
var forwardGeocodoResults = await client.ForwardGeocodeAsync("3850 S Las Vegas Blvd, Las Vegas, NV 89109", fields);
var result = forwardGeocodoResults.Results[0].Response.Results[0];
//Put in a break point to examine the dictionary exposed by Economics and see how many keys and groupings we get, it's quite a bit!
var dataItem = result.Fields.ACS_Results.Economics["Household Income"]["$60,000 to $74,999"];