Updated the readme to match the new code.

README.md

@@ -3,61 +3,81 @@ LocationByZip
 
 This library provides a small set of methods to work with U.S. ZIP Codes. With it, you can:
 
-* Retrieve a City/State by ZIP Code.
-* Retrieve a collection of one or more ZIP Codes that correspond to a City/State
-* Retrieve a collection of locations that fall within a given radius of a certain ZIP Code
+* Get locations that fall within a given radius (in miles) of a certain ZIP Code
+* Get a City/State by ZIP Code
+* Get a collection of one or more ZIP Codes by City/State
 * Determine the distance (in miles) between two ZIP Codes
 
-This is a code refresh of an article I wrote at The Code Project: [ZIP Code Utility](http://www.codeproject.com/Articles/9198/ZIP-Code-Utility)
-
-Instead of an Access database (which is no longer available for download), this code assumes you are using a SQL Server 2005+ database server. From the [Releases](https://github.com/jonsagara/LocationByZip/releases/tag/3.0.0) page, you can download the SQL script that creates and populates the ZipCode table.
+This project uses the [geonames](https://www.geonames.org) [US Postal Code](https://download.geonames.org/export/zip/) file under the 
+Creative Commons Attribution 3.0 License.
 
 Usage
 -----
 
-To begin with, you instantiate an instance of the LocationService class:
+In `DemoConsoleApp`, you'll see a .NET Core Generic Host set up to inject `LocationService` and `SqlLocationRepository`. You can use
+a similar setup in, e.g., an ASP.NET Core MVC application, although with a web application, you'd likely want to add them as scoped services.
 
 ```csharp
-ILocationService locationSvc = new LocationService();
+services.AddTransient<LocationService, LocationService>();
+services.AddTransient<ILocationRepository, SqlLocationRepository>();
 ```
 
-Using this instance, you can then call the various methods on the ILocationService interface.
+You can then get an injected instance of `LocationService`.
 
-To look up a Location by ZIP Code:
+To find all Locations within a given radius:
 
 ```csharp
-Location location = locationSvc.GetByZipCode("93275");
+// IReadOnlyCollection<LocationInRadius>
+var locationsInRadius = locationSvc.GetLocationsInRadius("93401", 10.0);
 ```
 
-To look up a collection of Locations by City/State:
+To look up a Location by ZIP Code:
 
 ```csharp
-IEnumerable<Location> locs = locationSvc.GetByCityState("Tulare", "CA");
+// Location
+var location = locationSvc.GetByZipCode("93275");
 ```
 
-To find all Locations within a given radius:
+To look up a collection of Locations by City/State:
 
 ```csharp
-IEnumerable<LocationInRadius> locsInRadius = locationSvc.GetLocationsInRadius("93401", 10.0);
+// IReadOnlyCollection<Location>
+var locations = locationSvc.GetByCityState("Tulare", "CA");
 ```
 
 To find the distance (currently in miles) between two ZIP Codes:
 
 ```csharp
-double distance = locationSvc.GetDistanceBetweenLocations("93401", "93446");
+// double
+var distanceInMiles = locationSvc.GetDistanceBetweenLocations("93401", "93446");
 ```
 
-To see the results returned by these calls, create the ZipCode table in your SQL Server database, and then compile and run the LocationByZip.DemoConsoleApp project.
 
-Creating the ZipCode table
+Creating the ZipCodes table
 --------------------------
 
-This assumes that you are using SQL Server 2005 or above.
+In the `data` folder, you'll find a CSV dump of US Postal Codes from 2020-02-26. Before generating the CSV, I removed the following two 
+duplicates so that I could use `Zip5` as the primary key:
 
-1. From the [Releases](https://github.com/jonsagara/LocationByZip/releases/tag/3.0.0) page, download ZipCode.7z.
-2. Using [7-Zip](http://www.7-zip.org/) or your favorite decompressor, extract ZipCode.sql from ZipCode.7z.
-3. In SQL Server Management Studio, create or select a database where you want the ZipCode table to live.
-4. Open ZipCode.sql in a new query window, and ensure your database is selected.
-5. Run ZipCode.sql
+```
+Zip5 = '96860' AND PlaceName = 'FPO AA'
+Zip5 = '96863' AND PlaceName = 'FPO AA'
+```
+
+Import the CSV into the database of your choice. This code uses [Dapper](https://github.com/StackExchange/Dapper) to access a table named
+`ZipCodes` in a recent version of `SQL Server` .
+
+You can find and edit the SQL in `SqlLocationRepository.cs` in the `LocationByZip` project.
+
+The connection string is in `appsettings.json` in the `LocationByZip.DemoConsoleApp` project.
+
+
+History
+----------------
+
+This is a code refresh of an article I wrote at The Code Project: [ZIP Code Utility](http://www.codeproject.com/Articles/9198/ZIP-Code-Utility)
 
-That's it!
+* 2020-02-28: `4.0.0`: Converted to .NET Core 3.1.
+* 2013-12-19: Converted repo from `hg` to `git`. Hosted on GitHub.
+* 2010-10-13: `3.0.0`: Code modernization.
+* 2005-01-02: Initial release on CodeProject.

data/geonames_readme.txt

@@ -0,0 +1,47 @@
+Readme for GeoNames Postal Code files :
+
+allCountries.zip: all countries, for the UK only the outwards codes, the UK total codes are in GB_full.csv.zip 
+GB_full.csv.zip the full codes for the UK, ca 1.7 mio rows
+<iso countrycode>: country specific subset also included in allCountries.zip
+This work is licensed under a Creative Commons Attribution 3.0 License.
+This means you can use the dump as long as you give credit to geonames (a link on your website to www.geonames.org is ok)
+see http://creativecommons.org/licenses/by/3.0/
+UK (GB_full.csv.zip): Contains Royal Mail data Royal Mail copyright and database right 2017.
+The Data is provided "as is" without warranty or any representation of accuracy, timeliness or completeness.
+
+This readme describes the GeoNames Postal Code dataset.
+The main GeoNames gazetteer data extract is here: http://download.geonames.org/export/dump/
+
+
+For many countries lat/lng are determined with an algorithm that searches the place names in the main geonames database 
+using administrative divisions and numerical vicinity of the postal codes as factors in the disambiguation of place names. 
+For postal codes and place name for which no corresponding toponym in the main geonames database could be found an average 
+lat/lng of 'neighbouring' postal codes is calculated.
+Please let us know if you find any errors in the data set. Thanks
+
+For Canada we have only the first letters of the full postal codes (for copyright reasons)
+
+For Chile we have only the first digits of the full postal codes (for copyright reasons)
+
+For Ireland we have only the first letters of the full postal codes (for copyright reasons)
+
+For Malta we have only the first letters of the full postal codes (for copyright reasons)
+
+The Argentina data file contains the first 5 positions of the postal code.
+
+For Brazil only major postal codes are available (only the codes ending with -000 and the major code per municipality).
+
+The data format is tab-delimited text in utf8 encoding, with the following fields :
+
+country code      : iso country code, 2 characters
+postal code       : varchar(20)
+place name        : varchar(180)
+admin name1       : 1. order subdivision (state) varchar(100)
+admin code1       : 1. order subdivision (state) varchar(20)
+admin name2       : 2. order subdivision (county/province) varchar(100)
+admin code2       : 2. order subdivision (county/province) varchar(20)
+admin name3       : 3. order subdivision (community) varchar(100)
+admin code3       : 3. order subdivision (community) varchar(20)
+latitude          : estimated latitude (wgs84)
+longitude         : estimated longitude (wgs84)
+accuracy          : accuracy of lat/lng from 1=estimated, 4=geonameid, 6=centroid of addresses or shape