Table Of Contents
What is RESTCountries.NET?
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:
- Retrieve a list of countries in multiple languages.
- Search by country name, the capital city, currency code.
- Search by continent: Africa, America, Asia, Europe, Oceania.
- Search by regional bloc like European Union, Africa Union, ... etc
So through this blog post, I will share with you how we can use this library to get this information.
Installation
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
Usage
- Get a list of all countries
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.
- Search by country name
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.
- Search by country full name
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.
- Search by ISO 3166-1 2-letter or 3-letter country code
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountryByCodeAsync("us");
Console.WriteLine(result.Name);
// Should print "United States of America"
- Search by a list of ISO 3166-1 2-letter or 3-letter country codes
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByCodesAsync("us", "fr", "ca");
// Will return a list of 3 countries
- Search by ISO 4217 currency code
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByCurrencyCodeAsync("eur");
- Search by ISO 639-1 language code
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByLanguageCodeAsync("en");
// Will return a list of commonwealth countries
- Search by capital name
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountryByCapitalCityAsync("lome");
Console.WriteLine(result.Name);
// Should print "Togo"
- Search by calling code.
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
- Search by regional bloc: EU, EFTA, CARICOM, AU, USAN, EEU, AL, ASEAN, CAIS, CEFTA, NAFTA or SAARC.
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).
- Search by continent: Africa, Americas, Asia, Europe, Oceania
using RESTCountries.Services;
var result = await RESTCountriesAPI.GetCountriesByContinentAsync("africa");
- Apply filters
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.
Cons of RESTCountries.NET
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 future of RESTCountries.NET
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.
Support
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.
Share
Microsoft MVP | Founder
Quick Links