HawkN.Iso.Countries

Part of the HawkN.Iso reference framework.

	HawkN.Iso.Countries provides ISO 3166-1 country codes (Alpha-2, Alpha-3), official names, numeric codes (UN M49), and validation services.

---

Features

HawkN.Iso.Countries (Core)

• Comprehensive Country List – Provides an up-to-date ISO 3166-1 country data with numeric codes from UN M49.
• Strongly Typed Codes – TwoLetterCode and ThreeLetterCode enums are generated at compile-time.
• Multiple Search Methods – Lookup by Alpha-2, Alpha-3, Numeric code, or Country Name.
• Advanced Validation – Built-in ValidationResult providing detailed feedback for code and name verification.
• Ultra-Fast Performance – O(1) lookups via pre-indexed static dictionaries.
• Lightweight & Dependency-Free – Compatible with .NET 8 and above.

HawkN.Iso.Countries.Currencies (Extension)

• Primary and Secondary Currencies – Get the main currency or all secondary currencies of a country.
• Fast Lookups – O(1) lookups using pre-indexed dictionaries and HashSet for secondary currencies.
• Currency Validation – Check if a country uses a given currency.
• Seamless Integration – Built to work with HawkN.Iso.Countries types (CountryCode.TwoLetterCode).
• Lightweight & Dependency-Free – Compatible with .NET 8 and above.

---

Packages

Package	Description
	Main library with country models, validation services, and generated ISO enums (Alpha-2, Alpha-3).
	Provides ISO-based mapping of primary and secondary currencies for countries.It allows you to quickly retrieve the main currency, secondary currencies, all currencies, or check if a currency is used by a specific country.

---

Getting Started

Install via NuGet

dotnet add package HawkN.Iso.Countries

Required Namespaces

HawkN.Iso.Countries (Core)

using HawkN.Iso.Countries;
using HawkN.Iso.Countries.Abstractions;
using HawkN.Iso.Countries.Models;
using HawkN.Iso.Countries.Extensions;

HawkN.Iso.Countries.Currencies (Extension)

using HawkN.Iso.Countries;
using HawkN.Iso.Currencies;
using HawkN.Iso.Countries.Currencies.Extensions;

---

Usage Example

HawkN.Iso.Countries (Core)

Registration

Register the service in your DI container:

using var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddCountryCodeService();
    })
    .Build();

Retrieval & Search

The service provides O(1) lookups via pre-indexed dictionaries and efficient partial searching.

var service = scope.ServiceProvider.GetRequiredService<ICountryCodeService>();

// Get all countries sorted by name
var countries = service.GetAll();

// Lookup by string (Supports Alpha-2, Alpha-3, or Numeric)
var germany = service.FindByCode("DE");
var austria = service.FindByCode("040");

// Lookup by Name
var france = service.FindByName("France");

// Strongly typed lookup
var uk = service.Get(CountryCode.TwoLetterCode.GB);

// Scenario: User types "Republic" in a search box
var searchResults = service.SearchByName("Republic");

foreach (var country in searchResults)
{
    // Will return:
    // 1. Republic of Korea
    // 2. Czech Republic
    // 3. Lao People's Democratic Republic...
    Console.WriteLine($"{country.Name} ({country.OfficialName})");
}

// Pro Tip: Use for suggestion lists
var suggestions = service.SearchByName("United")
    .Select(c => c.Name)
    .Take(5); 
// Returns: ["United Arab Emirates", "United Kingdom", "United States", ...]

Validation

Check if a code or name is valid and retrieve the model simultaneously:

// Validate by Code
var result = service.ValidateByCode("US", out var country);
if (result.IsValid)
{
    Console.WriteLine($"Found: {country.Name}");
}

// Validate by Name
var nameResult = service.ValidateByName("Unknown Land", out _);
if (!nameResult.IsValid)
{
    Console.WriteLine($"Error: {nameResult.Reason}"); 
}

Fluent String Extensions

string input = "FRA";

// Direct conversion
var country = input.ToCountry(service);

// Quick check
if ("US".IsCountryCode(service)) 
{
    // ...
}

// Quick validation
var validationResult = "US".ValidateAsCountryCode(countryCodeService, out var _);
if (validationResult.IsValid)
{
   // ...
}

Emoji Flags Support

The library provides an easy way to display country flags using standard Unicode Emoji. This works without any external image assets and is perfect for lightweight UI components.

var country = service.Get(CountryCode.TwoLetterCode.FI);

// Get the emoji flag using the extension method
string flag = country.GetEmojiFlag(); 

Console.WriteLine($"{flag} {country.Name}"); 
// Output: 🇫🇮 Finland

HawkN.Iso.Countries.Currencies (Extension)

Currency mapping

var country = CountryCode.TwoLetterCode.CH;

// Primary currency
var primary = country.GetPrimaryCurrency();   // CHF

// Secondary currencies
var secondary = country.GetSecondaryCurrencies();

// All currencies
var all = country.GetAllCurrencies();

// Check if used
bool usesChe = country.IsCurrencyUsedByCountry(CurrencyCode.CHE);

Validation

// Check if used the currency
bool usesChe = country.IsCurrencyUsedByCountry(CurrencyCode.CHE);

---

Supported countries

Click to view the full list of supported countries

Alpha-2	Alpha-3	Numeric (string)	Country Name
AF	AFG	004	Afghanistan
AL	ALB	008	Albania
DZ	DZA	012	Algeria
AS	ASM	016	American Samoa
AD	AND	020	Andorra
AO	AGO	024	Angola
AI	AIA	660	Anguilla
AQ	ATA	010	Antarctica
AG	ATG	028	Antigua and Barbuda
AR	ARG	032	Argentina
AM	ARM	051	Armenia
AW	ABW	533	Aruba
AU	AUS	036	Australia
AT	AUT	040	Austria
AZ	AZE	031	Azerbaijan
BS	BHS	044	Bahamas
BH	BHR	048	Bahrain
BD	BGD	050	Bangladesh
BB	BRB	052	Barbados
BY	BLR	112	Belarus
BE	BEL	056	Belgium
BZ	BLZ	084	Belize
BJ	BEN	204	Benin
BM	BMU	060	Bermuda
BT	BTN	064	Bhutan
BO	BOL	068	Bolivia (Plurinational State of)
BQ	BES	535	Bonaire, Sint Eustatius and Saba
BA	BIH	070	Bosnia and Herzegovina
BW	BWA	072	Botswana
BV	BVT	074	Bouvet Island
BR	BRA	076	Brazil
IO	IOT	086	British Indian Ocean Territory
VG	VGB	092	British Virgin Islands
BN	BRN	096	Brunei Darussalam
BG	BGR	100	Bulgaria
BF	BFA	854	Burkina Faso
BI	BDI	108	Burundi
CV	CPV	132	Cabo Verde
KH	KHM	116	Cambodia
CM	CMR	120	Cameroon
CA	CAN	124	Canada
KY	CYM	136	Cayman Islands
CF	CAF	140	Central African Republic
TD	TCD	148	Chad
CL	CHL	152	Chile
CN	CHN	156	China
HK	HKG	344	China, Hong Kong Special Administrative Region
MO	MAC	446	China, Macao Special Administrative Region
CX	CXR	162	Christmas Island
CC	CCK	166	Cocos (Keeling) Islands
CO	COL	170	Colombia
KM	COM	174	Comoros
CG	COG	178	Congo
CK	COK	184	Cook Islands
CR	CRI	188	Costa Rica
HR	HRV	191	Croatia
CU	CUB	192	Cuba
CW	CUW	531	Curaçao
CY	CYP	196	Cyprus
CZ	CZE	203	Czechia
CI	CIV	384	Côte d’Ivoire
KP	PRK	408	Democratic People's Republic of Korea
CD	COD	180	Democratic Republic of the Congo
DK	DNK	208	Denmark
DJ	DJI	262	Djibouti
DM	DMA	212	Dominica
DO	DOM	214	Dominican Republic
EC	ECU	218	Ecuador
EG	EGY	818	Egypt
SV	SLV	222	El Salvador
GQ	GNQ	226	Equatorial Guinea
ER	ERI	232	Eritrea
EE	EST	233	Estonia
SZ	SWZ	748	Eswatini
ET	ETH	231	Ethiopia
FK	FLK	238	Falkland Islands (Malvinas)
FO	FRO	234	Faroe Islands
FJ	FJI	242	Fiji
FI	FIN	246	Finland
FR	FRA	250	France
GF	GUF	254	French Guiana
PF	PYF	258	French Polynesia
TF	ATF	260	French Southern Territories
GA	GAB	266	Gabon
GM	GMB	270	Gambia
GE	GEO	268	Georgia
DE	DEU	276	Germany
GH	GHA	288	Ghana
GI	GIB	292	Gibraltar
GR	GRC	300	Greece
GL	GRL	304	Greenland
GD	GRD	308	Grenada
GP	GLP	312	Guadeloupe
GU	GUM	316	Guam
GT	GTM	320	Guatemala
GG	GGY	831	Guernsey
GN	GIN	324	Guinea
GW	GNB	624	Guinea-Bissau
GY	GUY	328	Guyana
HT	HTI	332	Haiti
HM	HMD	334	Heard Island and McDonald Islands
VA	VAT	336	Holy See
HN	HND	340	Honduras
HU	HUN	348	Hungary
IS	ISL	352	Iceland
IN	IND	356	India
ID	IDN	360	Indonesia
IR	IRN	364	Iran (Islamic Republic of)
IQ	IRQ	368	Iraq
IE	IRL	372	Ireland
IM	IMN	833	Isle of Man
IL	ISR	376	Israel
IT	ITA	380	Italy
JM	JAM	388	Jamaica
JP	JPN	392	Japan
JE	JEY	832	Jersey
JO	JOR	400	Jordan
KZ	KAZ	398	Kazakhstan
KE	KEN	404	Kenya
KI	KIR	296	Kiribati
KW	KWT	414	Kuwait
KG	KGZ	417	Kyrgyzstan
LA	LAO	418	Lao People's Democratic Republic
LV	LVA	428	Latvia
LB	LBN	422	Lebanon
LS	LSO	426	Lesotho
LR	LBR	430	Liberia
LY	LBY	434	Libya
LI	LIE	438	Liechtenstein
LT	LTU	440	Lithuania
LU	LUX	442	Luxembourg
MG	MDG	450	Madagascar
MW	MWI	454	Malawi
MY	MYS	458	Malaysia
MV	MDV	462	Maldives
ML	MLI	466	Mali
MT	MLT	470	Malta
MH	MHL	584	Marshall Islands
MQ	MTQ	474	Martinique
MR	MRT	478	Mauritania
MU	MUS	480	Mauritius
YT	MYT	175	Mayotte
MX	MEX	484	Mexico
FM	FSM	583	Micronesia (Federated States of)
MC	MCO	492	Monaco
MN	MNG	496	Mongolia
ME	MNE	499	Montenegro
MS	MSR	500	Montserrat
MA	MAR	504	Morocco
MZ	MOZ	508	Mozambique
MM	MMR	104	Myanmar
NA	NAM	516	Namibia
NR	NRU	520	Nauru
NP	NPL	524	Nepal
NL	NLD	528	Netherlands (Kingdom of the)
NC	NCL	540	New Caledonia
NZ	NZL	554	New Zealand
NI	NIC	558	Nicaragua
NE	NER	562	Niger
NG	NGA	566	Nigeria
NU	NIU	570	Niue
NF	NFK	574	Norfolk Island
MK	MKD	807	North Macedonia
MP	MNP	580	Northern Mariana Islands
NO	NOR	578	Norway
OM	OMN	512	Oman
PK	PAK	586	Pakistan
PW	PLW	585	Palau
PA	PAN	591	Panama
PG	PNG	598	Papua New Guinea
PY	PRY	600	Paraguay
PE	PER	604	Peru
PH	PHL	608	Philippines
PN	PCN	612	Pitcairn
PL	POL	616	Poland
PT	PRT	620	Portugal
PR	PRI	630	Puerto Rico
QA	QAT	634	Qatar
KR	KOR	410	Republic of Korea
MD	MDA	498	Republic of Moldova
RO	ROU	642	Romania
RU	RUS	643	Russian Federation
RW	RWA	646	Rwanda
RE	REU	638	Réunion
BL	BLM	652	Saint Barthélemy
SH	SHN	654	Saint Helena
KN	KNA	659	Saint Kitts and Nevis
LC	LCA	662	Saint Lucia
MF	MAF	663	Saint Martin (French Part)
PM	SPM	666	Saint Pierre and Miquelon
VC	VCT	670	Saint Vincent and the Grenadines
WS	WSM	882	Samoa
SM	SMR	674	San Marino
ST	STP	678	Sao Tome and Principe
SA	SAU	682	Saudi Arabia
SN	SEN	686	Senegal
RS	SRB	688	Serbia
SC	SYC	690	Seychelles
SL	SLE	694	Sierra Leone
SG	SGP	702	Singapore
SX	SXM	534	Sint Maarten (Dutch part)
SK	SVK	703	Slovakia
SI	SVN	705	Slovenia
SB	SLB	090	Solomon Islands
SO	SOM	706	Somalia
ZA	ZAF	710	South Africa
GS	SGS	239	South Georgia and the South Sandwich Islands
SS	SSD	728	South Sudan
ES	ESP	724	Spain
LK	LKA	144	Sri Lanka
PS	PSE	275	State of Palestine
SD	SDN	729	Sudan
SR	SUR	740	Suriname
SJ	SJM	744	Svalbard and Jan Mayen Islands
SE	SWE	752	Sweden
CH	CHE	756	Switzerland
SY	SYR	760	Syrian Arab Republic
TJ	TJK	762	Tajikistan
TH	THA	764	Thailand
TL	TLS	626	Timor-Leste
TG	TGO	768	Togo
TK	TKL	772	Tokelau
TO	TON	776	Tonga
TT	TTO	780	Trinidad and Tobago
TN	TUN	788	Tunisia
TM	TKM	795	Turkmenistan
TC	TCA	796	Turks and Caicos Islands
TV	TUV	798	Tuvalu
TR	TUR	792	Türkiye
UG	UGA	800	Uganda
UA	UKR	804	Ukraine
AE	ARE	784	United Arab Emirates
GB	GBR	826	United Kingdom of Great Britain and Northern Ireland
TZ	TZA	834	United Republic of Tanzania
UM	UMI	581	United States Minor Outlying Islands
VI	VIR	850	United States Virgin Islands
US	USA	840	United States of America
UY	URY	858	Uruguay
UZ	UZB	860	Uzbekistan
VU	VUT	548	Vanuatu
VE	VEN	862	Venezuela (Bolivarian Republic of)
VN	VNM	704	Viet Nam
WF	WLF	876	Wallis and Futuna Islands
EH	ESH	732	Western Sahara
YE	YEM	887	Yemen
ZM	ZMB	894	Zambia
ZW	ZWE	716	Zimbabwe
AX	ALA	248	Åland Islands

Last updated at 25.12.2025.

---

Generated Types

• CountryCode.TwoLetterCode – Enum for Alpha-2 codes (e.g., US, GB).
• CountryCode.ThreeLetterCode – Enum for Alpha-3 codes (e.g., USA, GBR).
• Country – Model containing Name, enums, string codes, NumericCode and NumericCodeString.

---

License

Code

This project’s source code is licensed under the MIT License.

Data

This project uses data derived from the following sources:

• Unicode Common Locale Data Repository (CLDR)
  Licensed under the Unicode License Agreement.

• Country data (ISO 3166-1 and UN M49 numeric codes) is sourced from the UN Statistics Division – M49 standard

The above data licenses are permissive and compatible with MIT-licensed code
when used for reference and code generation.

---

Troubleshooting: Emoji Display

If you see ?? instead of flags in your console:

1. Ensure your console output encoding is set to UTF-8: Console.OutputEncoding = System.Text.Encoding.UTF8;
2. Use a modern terminal like Windows Terminal or VS Code Terminal.
3. Use a font that supports Emojis (e.g., Segoe UI Emoji or Cascadia Code).

---

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you want to contribute code, feel free to submit a Pull Request.

1. Fork the repository.
2. Create a new branch (git checkout -b feature/awesome-feature).
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.

---

References

• ISO 3166 Standard
• UN Statistics Division – M49 standard
• GitHub Repository