RESTCountries.NET is a .NET Standard wrapper around the API (version 2) provided by restcountries.com. I created its NuGet package 3 years ago to populate a country list in one of my .NET Core projects.
As I am writing this article, the library hits 9k downloads, which isn't bad at all, but I'm really surprised that people are using this tool.
Below is the summary of what can be achieved with the library:
So through this blog post, I will share with you how we can use this library to get this information.
The NuGet package can be installed into any .NET project, to do that, you can use either the NuGet Package Manager
or the Package Manager Console
. You can also use the .NET CLI
.
I am going to use the .NET CLI:
dotnet add package RESTCountries.NET
using RESTCountries.Services;
using RESTCountries.Models;
List<Country> countries = await RESTCountriesAPI.GetAllCountriesAsync();
I am using explicit types to show you the return type of the GetAllCountriesAsync()
method. Take a look at the Country class here.
The name can be a full name or a partial name.
using RESTCountries.Services;
using RESTCountries.Models;
List<Country> result = await RESTCountriesAPI.GetCountriesByNameContainsAsync("tog");
// Will return a list of one country which is Togo
If a partial name has been provided, this method could return a list of countries, otherwise a list of one element.
using RESTCountries.Services;
using RESTCountries.Models;
Country result = await RESTCountriesAPI.GetCountryByFullNameAsync("italy");
As you may have noticed, the previous method(GetCountriesByNameContainsAsync
), can do the same if a full name is provided.
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountryByCodeAsync("us");
Console.WriteLine(result.Name);
// Should print "United States of America"
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByCodesAsync("us", "fr", "ca");
// Will return a list of 3 countries
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByCurrencyCodeAsync("eur");
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByLanguageCodeAsync("en");
// Will return a list of commonwealth countries
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountryByCapitalCityAsync("lome");
Console.WriteLine(result.Name);
// Should print "Togo"
using RESTCountries.Services;
using RESTCountries.Models;
List<Country> result = await RESTCountriesAPI.GetCountriesByCallingCodeAsync("33");
If you are wondering why this method returns a list of countries instead of a single country, that's because country code 1 for example is used in the USA and also in Canada. To verify that, check the List of country calling codes on Wikipedia
using RESTCountries.Services;
using RESTCountries.Models;
List<Country> result = await RESTCountriesAPI.GetCountriesByRegionalBlocAsync("AU"); // "AU" stands for "African Union"
EU (European Union), EFTA (European Free Trade Association), CARICOM (Caribbean Community), PA (Pacific Alliance), AU (African Union), USAN (Union of South American Nations), EEU (Eurasian Economic Union), AL (Arab League), ASEAN (Association of Southeast Asian Nations), CAIS (Central American Integration System), CEFTA (Central European Free Trade Agreement), NAFTA (North American Free Trade Agreement), SAARC (South Asian Association for Regional Cooperation).
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByContinentAsync("africa");
using RESTCountries.Services;
// Get all countries in Spanish language
var countries = await RESTCountriesAPI.GetAllCountriesAsync();
List<string> countriesInEs = countries.Select(c => c.Translations.Es).ToList();
// Get Europe countries in French language
var europeCountries = await RESTCountriesAPI.GetCountriesByContinentAsync("Europe");
List<string> europeCountriesInFr = europeCountries.Select(c => c.Translations.Fr).ToList();
// Fell free to apply filters 🤓
RESTCountries.NET is a very cool project, isn't it? Now, I would like to share some issues we may face.
Since I used an API to retrieve information, the library would be useless if the source is down. Another point is that many projects use the API, according to its author, they’re getting about 1.6 million requests every day and that means also bandwidth (25 GB per day!), so costs have increased.
This is why I mentioned a road map at the beginning of this article. The idea is to fix the issue I described above.
The important thing to do in the next months is to add an offline mode to the library. An issue was already created by myself on GitHub.
If you find this article useful, please give a start :star: to the project on GitHub. Feel free to create an issue or make a pull request. To send me a message, please use the contact form or DM me on Twitter.
Quick Links