MaksimShimshon.RestCountries.Embedded 0.9.41

🌍 RestCountries C# Port

This C# library is a full port of the REST Countries Java API, preserving full compatibility with the original JSON structure (v3.1 and v3).

It provides strongly typed access to rich country and region data, ideal for .NET developers building apps that need detailed country-related information.

The package supports dependency injection for seamless integration into modern web applications.

It also includes high test coverage, making it production-ready.

🔑 Key Features

• Access detailed country data: name, capital, region, population, area, and more
• Retrieve languages, currencies, and translations of country names
• Time zone support for all countries
• Strongly typed models for easy C# integration
• Fully compatible with original REST Countries JSON formats
• Built-in support for ASP.NET dependency injection

Perfect for apps that need reliable, structured, and localized country information.

Important Information

• We are supporting REST Countries Java (Alejandro Matos) Version 3, Version 3.1 and plan the maintain compatibility.
• Versions will be updated according to REST Countries Java version updates.
• Consider contribution to the JSON data for REST Countries Java.

Pakages

MaksimShimshon.RestCountries

This .NET 8 based pakage contains the core behaviour for the RestCountries without any dependencies.

using MaksimShimshon.RestCountries;
using MaksimShimshon.RestCountries.Data;
var builder = WebApplication.CreateBuilder(args);
// this will make a singleton accessible through IRestCountries.
// replace RestCountriesEmbed.GetVersion("countriesV3.1") by your local or remote verson.json file.
builder.Services.AddRestCountriesServices(RestCountriesEmbed.GetVersion());

MaksimShimshon.RestCountries.Embedded

📦 Package Size Consideration

The Embedded package includes all available JSON versions, which significantly increases its size.
This may not be suitable for front-end deployments due to payload concerns.

However, it is ideal for server-side use, where having access to multiple versions of the data can be valuable.

using MaksimShimshon.RestCountries;
using MaksimShimshon.RestCountries.Embedded;
var builder = WebApplication.CreateBuilder(args);
// this will make a singleton accessible through IRestCountries.
builder.Services.AddRestCountriesServices(RestCountriesEmbed.GetVersion("countriesV3.1"));

MaksimShimshon.RestCountries.Data

⚠️ Important Compatibility Notice

This package must not be installed alongside the MaksimShimshon.RestCountries.Embedded package.
A conflict has been intentionally introduced by using the same RestCountriesEmbed class in both packages to avoid incompatibility.

• **Embedded** includes all available JSON versions.
• **Data** includes only the targeted version.

As a result, the version of the Data package you install will match the version of the original REST Countries JSON data available in your project.

using MaksimShimshon.RestCountries;
using MaksimShimshon.RestCountries.Data;
var builder = WebApplication.CreateBuilder(args);
// this will make a singleton accessible through IRestCountries.
builder.Services.AddRestCountriesServices(RestCountriesEmbed.GetVersion());

Fields

You can check the FIELDS.md file to get info on each classes.

Getting Started

using MaksimShimshon.RestCountries.Embedded;

// Replace this to the json content of the version.json or use embeded content.
string jsonContentOfVersion = RestCountriesEmbed.GetVersion("countriesV3.1");
IRestCountries restCountries = new RestCountries(jsonContentOfVersion);
var countries = restCountries.GetAll();

Check if Postal Required

using MaksimShimshon.RestCountries.Embedded;

string jsonContentOfVersion = RestCountriesEmbed.GetVersion(version);
IRestCountries restCountries = new RestCountries(jsonContentOfVersion);
var countries = restCountries.GetAll();
var firstCountry = countries.First();
if (firstCountry.IsPostalRequired()) 
    Console.WriteLine($"{firstCountry.Name.Common} does require postal of format: {firstCountry.PostalFormat!.Format}");
else
    Console.WriteLine($"{firstCountry.Name.Common} does not require a postal.");

Fetch Country by ISO-2 & Validate its postal code

using MaksimShimshon.RestCountries.Embedded;

string jsonContentOfVersion = RestCountriesEmbed.GetVersion(version);
IRestCountries restCountries = new RestCountries(jsonContentOfVersion);
var countries = restCountries.GetAll();
// ca = Canada. You could also do CCA3 with CAN.
var firstCountry = restCountries.IsValidCCA2Code("ca");
if (restCountries.IsValidCCA2Code("ca"))
    if (restCountries.GetByCCA2Code("cA")!.IsPostalValid("H1A2T2")) 
        Console.WriteLine("H1A2T2 is a valid postal for Canada");
    else
        Console.WriteLine($"ca is not a valid country iso2.");

More to Explore

Explore the other functions

using MaksimShimshon.RestCountries.Embedded;

string jsonContentOfVersion = RestCountriesEmbed.GetVersion(version);
IRestCountries restCountries = new RestCountries(jsonContentOfVersion);
var countries = restCountries.GetAll();
if (restCountries.IsValidCCA2Code("ca")) Console.WriteLine("This is valid country code.");
if (restCountries.IsValidCCA3Code("can")) Console.WriteLine("This is valid country code.");
if (restCountries.IsValidCCA2PostalCode("ca", "H1T2S2")) Console.WriteLine("This is valid country code and postal.");
if (restCountries.IsValidCCA3PostalCode("can", "H1T2S2")) Console.WriteLine("This is valid country code and postal.");
if (restCountries.IsValidCCA2Currency("ca", "CAD")) Console.WriteLine("CAD is a valid Canadian Currency.");
if (restCountries.IsValidCCA3Currency("cad", "CAD")) Console.WriteLine("CAD is a valid Canadian Currency.");
if (restCountries.IsValidCCA3Currency("cad", "CAD")) Console.WriteLine("CAD is a valid Canadian Currency.");

var country = countries.First()!;
Console.WriteLine($"Phone Prefixes are {string.Join(',', country.PhonePrefixes())}");

Similar projects

• REST Countries Java (original)
• Countries of the world
• REST Countries Node.js
• REST Countries Ruby
• REST Countries Go
• REST Countries Python
• world-currencies