NISOCountries

Always up-to-date (.Net) ISO Country list

On many occasions I needed a list of ISO 3166-1 countrycodes (alpha2, alpha3 and/or numeric). And on many occasions I resorted to some 'hardcoded' list of values (usually included in a resource file of some sort). Ofcourse this is a maintenance nightmare because whenever this list changes you need to update your resource file (or worse: recompile or update your database or...).

This project provides a means of keeping your data up-to-date by retrieving the latest data from the web or any other source provided. NISOCounties.Core provides a set of interfaces, basesclasses etc. that help you implement your own data provider tailored to your needs. It also provides a class to easily look up these ISO 3166-1 codes.

Currently NISOCountries provides 5 packages that retrieve data from commonly used sources for ISO 3166-1 data:

1. NISOCountries.GeoNames retrieves data from geonames.org (specifically: countryInfo.txt)
2. NISOCountries.Ripe retrieves data from ripe.net (specifically: iso3166-countrycodes.txt)
3. NISOCountries.Wikipedia.CSQ retrieves data from wikipedia (specifically ISO 3166-1, using CsQuery) - NO LONGER SUPPORTED / MAINTAINED since CsQuery doesn't support .Net Core / .Net Standard
4. NISOCountries.Wikipedia.HAP retrieves data from wikipedia (specifically ISO 3166-1, using Html Agility Pack)
5. NISOCountries.Datahub retrieves data from datahub.io (specifically /core/country-codes)

Everything is available as NuGet package.

Implementing your very own dataprovider is simple so feel free to add to the above list your very own!

NOTE: None of the above sources are 'official' and all of the above contain, sometimes subtly, different data. Which data you want to rely on is up to you.

Basic Usage

Usage is pretty straightforward. NISOCountries provides some convenience classes, methods etc. to hide most of the details you'll probably never use but more specific overloads, constructors etc. are available to tailor everything to your needs. The most basic 'hello world' example goes a little something like this:

//We choose, for this example, to use RIPE as source
using NISOCountries.Ripe;
using System;
using System.Linq;

class Program
{
    static void Main(string[] args)
    {
        //Retrieve ISO 3166-1 data from RIPE
        var countries = new RipeISOCountryReader().GetDefault();

        //Voila!
        Console.WriteLine(countries.Where(c => c.Alpha2 == "NL").Single().CountryName);
    }
}

Output:

Netherlands

NISOCountries.Core provides an ISOCountryLookup class that offers methods to lookup countries by their alpha-2, alpha-3 and numeric codes (e.g. "US", "USA", "840") and even provides "autodetection" of the type of code and TryGet() methods to handle non-existing codes more easily:

var countries = new RipeISOCountryReader().GetDefault();
var lookup = new ISOCountryLookup<RipeCountry>(countries);

//Use 'autodetection'
lookup.Get("US");
lookup.Get("USA");
lookup.Get("840");

//A bit more explicit:
lookup.GetByAlpha("US");
lookup.GetByAlpha("USA");

//Even more explicit:
lookup.GetByAlpha2("US");
lookup.GetByAlpha3("USA");
lookup.GetByNumeric("840");
lookup.GetByNumeric(840);

//TryGet methods
RipeCountry result;
lookup.TryGet("XX", out result);
lookup.TryGetByAlpha2("XX", out result);
lookup.TryGetByAlpha3("XXX", out result);
lookup.TryGetByNumeric("999", out result);

Core

The NISOCountry.Core library provides all required baseclasses and interfaces to be implemented when implementing your own country-data provider. A dataprovider is set of objects that implement interfaces like the IISOCountry, ISourceProvider and ISOCountryReader<T>. An ISOCountryReader<T> is the object that handles reading the underlying data (using the ISourceProvider and IStreamParser<T>), normalizing the data (using an IValueNormalizer<T>) and returning the normalized data as IEnumerable<T> where T implements IISOCountry. This way, you can create objects that read data from the web, files or other sources, have specific normalization rules (for example: uppercase all names or strip diacritics or...) and return data the way you want it. The ISOCountryLookup<T> and some classes implementing ISOCountryComparer<T> etc. are all provided in the core and more specific implementations may, or can, be provided by the provider-specific packages.

NISOCountries currently provides 5 implementations, as mentioned above, that provide guidance on how to implement your own dataprovider. Two of these implementations use Wikipedia and only differ in the way the data is extracted (using either CsQuery or the HtmlAgilityPack), one uses data from Ripe and one uses data from GeoNames.org. Some simple form of caching is built-in for these dataproviders to prevent the sources of the data being accessed too often ("play nice").

The library, or the packages if you will, is built to be extensible but still easy to use. There are many overloads and/or conveniencemethods that allow you to either be very specific in how you want to use the library and 'massaging' of the underlying data or to rely on default settings and keep it to a minimum.