{"id":22345910,"url":"https://github.com/youssefsell/countries.net","last_synced_at":"2025-07-30T03:32:30.860Z","repository":{"id":45484638,"uuid":"420687218","full_name":"YoussefSell/Countries.Net","owner":"YoussefSell","description":"Get access to an in-memory database of countries with no dependencies and no API calls.","archived":false,"fork":false,"pushed_at":"2022-02-26T12:31:09.000Z","size":549,"stargazers_count":5,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-17T10:47:28.035Z","etag":null,"topics":["countries","countries-database","csharp","dotnet","dotnet-core"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YoussefSell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-24T13:07:53.000Z","updated_at":"2023-05-09T17:55:54.000Z","dependencies_parsed_at":"2022-07-18T22:01:20.003Z","dependency_job_id":null,"html_url":"https://github.com/YoussefSell/Countries.Net","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/YoussefSell/Countries.Net","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoussefSell%2FCountries.Net","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoussefSell%2FCountries.Net/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoussefSell%2FCountries.Net/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoussefSell%2FCountries.Net/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YoussefSell","download_url":"https://codeload.github.com/YoussefSell/Countries.Net/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoussefSell%2FCountries.Net/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267803984,"owners_count":24146527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","countries-database","csharp","dotnet","dotnet-core"],"created_at":"2024-12-04T09:19:11.066Z","updated_at":"2025-07-30T03:32:30.424Z","avatar_url":"https://github.com/YoussefSell.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Countries.Net\n\n[![](https://img.shields.io/github/license/YoussefSell/Countries.Net)](https://github.com/YoussefSell/Countries.Net/blob/master/LICENSE)\n[![](https://img.shields.io/nuget/v/Countries.Net)](https://www.nuget.org/packages/Countries.Net/)\n![Build](https://github.com/YoussefSell/Countries.Net/actions/workflows/ci.yml/badge.svg)\n\nGet access to in-memory database of countries with an easy to use api and zero dependencies.\n\n## Quick setup\n\nto get started install the package using the [NuGet](https://www.nuget.org/packages/Countries.Net/) package manager `Install-Package Countries.Net`.\n\n## Country entity\n\nthe country entity expose the following properties:\n\n- `name`: the name of the country, a collection of key-value pairs where:\n  - `key`: three-letter ISO 639-3 language code.\n  - `value`: a country name object with:\n    - `official`: the official name of the country.\n    - `common`: the common name of the country.\n- `cca2`: code ISO 3166-1 alpha-2.\n- `cca3`: code ISO 3166-1 alpha-3.\n- `ccn3`: code ISO 3166-1 numeric.\n- `cioc`: code International Olympic Committee.\n- `independent`: ISO 3166-1 independence status (denotes the country is considered a sovereign state).\n- `status`: ISO 3166-1 assignment status.\n- `unMember`: UN Member status.\n- `flag`: the country flag.\n- `region`: the country region.\n- `subregion`: the country Subregion.\n- `landlocked`: the landlocked status.\n- `idd`: International Direct Dialing info, with:\n  - `root`: the root geographical code prefix. e.g. +6 for New Zealand, +4 for UK.\n  - `suffixes`: list of all suffixes assigned to this country. 4 for NZ, 809, 829, and 849 for Dominican Republic.\n- `borders`: the country land borders.\n- `capital`: the country capital city(ies).\n- `altSpellings`: the country alternative spellings.\n- `tld`: country top-level domain list.\n- `latlng`: latitude and longitude.\n- `timezones`: the country time zones.\n- `languages`: the country languages, with:\n  - `Name`: name of the language.\n  - `ISO6391`: the 2 chars code of the language.\n  - `ISO6392`: the 3 chars code of the language.\n- `currencies`: the country currencies, with:\n  - `Code`: code of the currency.\n  - `Name`: the name of the currency.\n  - `Symbol`: the symbol of the currency.\n- `demonyms`: name of residents, translated \u0026 genderized, a collection of key-value pairs where:\n  - `key`: three-letter ISO 639-3 language code.\n  - `value`: genderized demonym object with:\n    - `male`: the male resident name.\n    - `female`: the female resident name.\n\nhere is a json representation of the country entity:\n\n```json\n{\n  \"Name\": {\n    \"eng\": { \"Official\": \"Kingdom of Morocco\", \"Common\": \"Morocco\" },\n    \"ara\": { \"Official\": \"المملكة المغربية\", \"Common\": \"المغرب\" },\n    \"fra\": { \"Official\": \"Royaume du Maroc\", \"Common\": \"Maroc\" },\n    \"spa\": { \"Official\": \"Reino de Marruecos\", \"Common\": \"Marruecos\" }\n  },\n  \"CCA2\": \"MA\",\n  \"CCA3\": \"MAR\",\n  \"CCN3\": \"504\",\n  \"CIOC\": \"MAR\",\n  \"Flag\": \"🇲🇦\",\n  \"Region\": 0,\n  \"Subregion\": \"Northern Africa\",\n  \"Independent\": true,\n  \"Status\": \"officially-assigned\",\n  \"UnMember\": true,\n  \"Landlocked\": false,\n  \"IDD\": { \"Root\": \"+2\", \"Suffixes\": [\"12\"] },\n  \"Borders\": [\"DZA\", \"ESH\", \"ESP\"],\n  \"Capital\": [\"Rabat\"],\n  \"AltSpellings\": [\"MA\", \"Kingdom of Morocco\", \"Al-Mamlakah al-Maġribiyah\"],\n  \"TLD\": [\".ma\", \"المغرب.\"],\n  \"Latlng\": [32, -5],\n  \"Timezones\": [\"UTC\"],\n  \"Languages\": [\n    {\n      \"ISO6391\": \"ar\",\n      \"ISO6392\": \"ara\",\n      \"Name\": \"Arabic\"\n    },\n    {\n      \"ISO6391\": \"\",\n      \"ISO6392\": \"ber\",\n      \"Name\": \"Berber\"\n    }\n  ],\n  \"Currencies\": [\n    {\n      \"Code\": \"MAD\",\n      \"Name\": \"Moroccan dirham\",\n      \"Symbol\": \"د.م.\"\n    }\n  ],\n  \"Demonyms\": {\n    \"eng\": {\n      \"Male\": \"Moroccan\",\n      \"Female\": \"Moroccan\"\n    },\n    \"fra\": {\n      \"Male\": \"Moroccan\",\n      \"Female\": \"Moroccan\"\n    }\n  }\n}\n```\n\n## Usage\n\n### 1. working with names:\n\nto get the name of the county you can do an implicit conversion to string with:\n\n```csharp\n// get the morocco country instance.\nvar morocco = Countries.NET.Database.Morocco.Instance;\n\n// the name prop is LocalizedCountryName object,\n// but you can use the implicit conversion to get the name value.\nstring name = morocco.Name;\n```\n\nthe name of the country is a collection of translations for the common and official name, wrapped in a object type `LocalizedCountryName` this object type exposes 3 functions `GetName()`, `GetName(string languageCode)` \u0026 `GetName(string languageCode, bool useOfficialName)`\n\nstarting with `GetName(string languageCode, bool useOfficialName)` :\n\n```csharp\n// get the morocco country instance.\nvar morocco = Countries.NET.Database.Morocco.Instance;\n\n// get the official name of the country in the given language,\n// this example with get the French official name of the country\n// to use the common name, pass false instead of true.\nvar name = morocco.Name.GetName(\"fra\", true);\n```\n\nthis function will give you the name of the country in the given language and will return either the common or official name based on the `bool useOfficialName` parameters.\n\nif no translation has been found for the given language, an exception will be thrown (this is applied to all 3 functions), if you don't want to throw an exception you can change this behavior with the static `WorldCountriesConfiguration` configuration class:\n\n```csharp\n// by setting the `ThrowIfNameNotFoundForALanguage` option to false, null will be returned instead of throwing the exception.\nWorldCountriesConfiguration.ThrowIfNameNotFoundForALanguage = false;\n```\n\nfor the function `GetName(string languageCode)` it same as the previous one, the only difference is that the type of the returned name (common or official) will be detrmined from `WorldCountriesConfiguration` configuration class\n\n```csharp\n// if set to `true` we will return the official name of the country when retrieving the name,\n// if set to `false` the common name will be used, by default is set to `true`\nWorldCountriesConfiguration.UserOfficialNameWhenRetrievingCountryName = true;\n```\n\nfinally the function `GetName()` it relays on the `WorldCountriesConfiguration` configuration class to do it job.  \nfor the language to be used for retrieving the name is determined with this 2 options:\n\n- `DefaultLanguage`: the default language to be used when retrieving the name of the country with `GetName()` method, the default value is `eng`.\n- `UseCurrentCultureInfoForCountryName`: if set to `true` the `CultureInfo.CurrentCulture` language will be used when retrieving the name, otherwise `DefaultLanguage` will be used, by default is set to `false`.\n\n```csharp\n// the default language to be used with `GetName()` when retrieving the name of the country\nWorldCountriesConfiguration.DefaultLanguage = `eng`;\n\n// true to use the current CultureInfo language instead of DefaultLanguage\nWorldCountriesConfiguration.UseCurrentCultureInfoForCountryName = false;\n```\n\nwith that we can say that the implicit conversion of the country name to string is simply using the `GetName()` under the hood\n\n```csharp\npublic static implicit operator string(LocalizedCountryName names) =\u003e names.GetName();\n```\n\n-2 working the countries data:\n\nall countries are located in the `Database` namespace, and you can interact with it using the `CountriesService`.\n\n```csharp\n// init the service\nvar service = new Countries.NET.CountriesService();\n\n// to get the list of all countries:\nvar countries = service.GetAll();\n\n// find the country with the given CCA2, CCA3, CCN3 or CIOC code:\nvar country = service.FindByCode(\"MA\");\n\n// find the country by the name:\nvar country = service.FindByName(\"Maroc\");\n\n// find list of countries in a given region:\nvar countries = service.FindByRegion(Region.Africa);\n\n// find list of countries using the given language code:\nvar countries = service.FindByLanguage(\"ara\");\n\n// find list of countries using the given currency code:\nvar countries = service.FindByCurrency(\"MAD\");\n\n// get the list of countries as key-value, where the key is Country.CCA2 and the value is the name:\nKeyValuePair\u003cstring, string\u003e countries = service.GetAsKeyValue();\n```\n\nyou can find the list of all supported countries [here](https://github.com/YoussefSell/Countries.Net/blob/master/Countries.md).\n\n-3 using it with DI for ASP core\n\nif you want to use `the CountriesService` With DI you can register the service with the interface `ICountriesService`\n\n```csharp\nserviceCollection.AddSingleton\u003cICountriesService, CountriesService\u003e();\n```\n\nor you can install the `Countries.Net.DependencyInjection`,\n\n- package on [NuGet](https://www.nuget.org/packages/Countries.Net.DependencyInjection), or with package manager `Install-Package Countries.Net.DependencyInjection`.\n\nthan you simple add this line to your DI\n\n```csharp\nserviceCollection.AddCountries();\n\n// to access WorldCountriesConfiguration configuration\nserviceCollection.AddCountries(config =\u003e {\n  config.DefaultLanguage = \"eng\";\n  config.IgnoreCaseOnNameEqualityCheck = true;\n  config.ThrowIfNameNotFoundForALanguage = true;\n  config.UseCurrentCultureInfoForCountryName = false;\n  config.UserOfficialNameWhenRetrievingCountryName = true;\n});\n```\n\n## Samples\n\nhere are some samples of how you can integrate Countries.Net with different app types:\n\n- [Console app](https://github.com/YoussefSell/Countries.Net/tree/master/samples/Countries.Net.Samples.Console)\n- [ASP Core app](https://github.com/YoussefSell/Countries.Net/tree/master/samples/Countries.Net.Samples.AspCore)\n\n## Credits\n\nThanks to:\n\n- [RestCountries](https://restcountries.com) api for the countries data.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoussefsell%2Fcountries.net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoussefsell%2Fcountries.net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoussefsell%2Fcountries.net/lists"}