Cloud Geography

📦 New Package: This library is now available as AngryMonkey.CloudGeography on NuGet. This is the recommended package going forward with enhanced features, better performance, and comprehensive test coverage.

Summary

Cloud Geography is a .NET client library for geographic and financial data operations, including countries, currencies, languages, subdivisions, time zones, money, and international phone number parsing.

Migration Note: If you're using the legacy AngryMonkey.Cloud.Geography package, we recommend upgrading to AngryMonkey.CloudGeography for access to the latest features, including flexible country/currency/language search by name with alternative names support, and enhanced subdivision search with fuzzy matching.

Features

• Country lookup by code, name, alternative names, or calling code
• Country lookup by coordinates (requires Azure Maps API key)
• Country lookup by IP address (requires Azure Maps API key)
• Country guessing from phone numbers
• Currency lookup by code, name, or country
• Language lookup by code, name, or country
• Subdivision lookup by country code, name, or hierarchical queries
• Subdivision search with fuzzy matching and Arabic transliteration support
• Time zone lookup, conversion, and current time retrieval
• Money arithmetic helpers (add, subtract, decimal extraction)
• International phone number parsing and validation (country code, calling code, local number)

Quick Start

CloudGeographyClient client = new();

List<Country> countries = client.Countries.Get();
List<Currency> currencies = client.Currencies.Get();
List<Language> languages = client.Languages.Get();

Installation

Package Manager

Install-Package AngryMonkey.CloudGeography

.NET CLI

dotnet add package AngryMonkey.CloudGeography

Implementation

Namespace

using AngryMonkey.Cloud;
using AngryMonkey.Cloud.Geography;

Initialization

CloudGeographyClient cloudGeography = new CloudGeographyClient();

Usage

The following sections cover all supported API areas in CloudGeographyClient.

Countries

Get all countries

List<Country> countries = client.Countries.Get();

Get a country by code

// 2-letter code
Country country = client.Countries.Get("US");

// 3-letter code
Country country = client.Countries.Get("USA");

Get multiple countries by code

// 2-letter codes
string[] twoLettersCountryCodes = ["CA", "US"];
List<Country> countries = client.Countries.Get(twoLettersCountryCodes);

// 3-letter codes
string[] threeLettersCountryCodes = ["CAN", "USA"];
List<Country> countries = client.Countries.Get(threeLettersCountryCodes);

Get countries by calling code

Country country = client.Countries.GetByCallingCode(1);
// returns USA and Canada because they share the same calling code

Find a country by name

// Find by full name, short name, local name, or common alternative names
Country? country = client.Countries.Find("United States");
Country? country = client.Countries.Find("America");
Country? country = client.Countries.Find("Deutschland"); // Germany in German
Country? country = client.Countries.Find("لبنان"); // Lebanon in Arabic
Country? country = client.Countries.Find("UK"); // Alternative name for Great Britain

Find all countries matching a query

List<Country> countries = client.Countries.FindAll("Korea");
// returns all countries matching "Korea"

Guess country from phone number

Country? country = client.Countries.GuessCountryByPhoneNumber("+16265895784");
// US

Country? country = client.Countries.GuessCountryByPhoneNumber("+14185895784");
// CA (Canadian area code)

Get country by coordinates (requires Azure Maps API key)

CloudGeographyConfig config = new() { AzureMapsKey = "your-api-key" };
CloudGeographyClient client = new(config);

Coordinate coordinate = new(33.8464, 35.5343); // Lebanon coordinates
Country? country = await client.Countries.GetByCoordinates(coordinate);

Get country by IP address (requires Azure Maps API key)

CloudGeographyConfig config = new() { AzureMapsKey = "your-api-key" };
CloudGeographyClient client = new(config);

Country? country = await client.Countries.GetByIP("178.135.2.147");

Currencies

Get all currencies

List<Currency> currencies = client.Currencies.Get();

Get a currency by code

Currency currency = client.Currencies.Get("USD");

Get multiple currencies by code

string[] currencyCodes = ["AFN", "USD"];
List<Currency> currencies = client.Currencies.Get(currencyCodes);

Get currencies by country code

// 2-letter country code
List<CountryCurrency> currencies = client.Currencies.GetByCountry("US");

// 3-letter country code
List<CountryCurrency> currencies = client.Currencies.GetByCountry("USA");

// A country can have multiple currencies.

Find a currency by name

// Find by full name, short name, native name, or code
Currency? currency = client.Currencies.Find("United States Dollar");
Currency? currency = client.Currencies.Find("US Dollar");
Currency? currency = client.Currencies.Find("US Dollars");
Currency? currency = client.Currencies.Find("Euro");
Currency? currency = client.Currencies.Find("Lebanese pounds"); // plural form

Find all currencies matching a query

List<Currency> currencies = client.Currencies.FindAll("Dollar");
// returns all currencies matching "Dollar"

Languages

Get all languages

List<Language> languages = client.Languages.Get();

Get languages by language codes

string[] languageCodes = ["EN", "FR"];
List<Language> languages = client.Languages.Get(languageCodes);

Get languages by country code

// 2-letter country code
List<CountryLanguage> languages = client.Languages.GetByCountry("US");

// 3-letter country code
List<CountryLanguage> languages = client.Languages.GetByCountry("USA");

Get a language by code

// 2-letter code
Language? language = client.Languages.Get("EN");

// 3-letter code
Language? language = client.Languages.Get("ENG");

Find a language by name

// Find by English name, native name, or code
Language? language = client.Languages.Find("English");
Language? language = client.Languages.Find("French");
Language? language = client.Languages.Find("العربية"); // Arabic in Arabic script
Language? language = client.Languages.Find("日本語"); // Japanese in Japanese
Language? language = client.Languages.Find("español"); // Spanish in Spanish

Find all languages matching a query

List<Language> languages = client.Languages.FindAll("Arabic");
// returns all languages matching "Arabic"

Subdivisions

Get all subdivisions by country code

List<Subdivision> subdivisions = client.Subdivisions.Get("US");

Get multiple subdivisions by country and subdivision codes

string[] subdivisionCodes = ["AL", "AK", "AZ"];
List<Subdivision> subdivisions = client.Subdivisions.Get("US", subdivisionCodes);

Get a subdivision by country and subdivision code

Subdivision? subdivision = client.Subdivisions.Get("US", "AL");

Get child subdivisions

// Get all children of a subdivision (for hierarchical subdivisions)
List<Subdivision>? children = client.Subdivisions.GetChildren("LB", "BA");

// Get a specific child subdivision
Subdivision? child = client.Subdivisions.GetChild("LB", "BA", "BAS");

Get all subdivisions (flattened)

// Returns all subdivisions at all hierarchy levels as a flat list
List<Subdivision> allSubdivisions = client.Subdivisions.GetAll("US");

Find a subdivision by name

// Find by code or name (English or local language)
Subdivision? subdivision = client.Subdivisions.Find("US", "California");
Subdivision? subdivision = client.Subdivisions.Find("LB", "Mount Lebanon");
Subdivision? subdivision = client.Subdivisions.Find("LB", "جبل لبنان"); // Arabic
Subdivision? subdivision = client.Subdivisions.Find("LB", "Matn"); // Alternative spelling of Matn

Find all subdivisions matching a query

List<Subdivision> subdivisions = client.Subdivisions.FindAll("US", "New");
// returns all subdivisions matching "New" (e.g., New York, New Mexico, New Hampshire)

Advanced subdivision search

// Rich search with multi-part queries, fuzzy matching, and Arabic transliteration
SubdivisionSearchRequest request = new()
{
    Query = "Mount Lebanon",
    CountryCode = "LB"
};
SubdivisionSearchResult? result = client.Subdivisions.Search(request);

// Search across all countries (returns highest scoring match)
SubdivisionSearchRequest globalRequest = new()
{
    Query = "California"
};
SubdivisionSearchResult? result = client.Subdivisions.Search(globalRequest);

// Search with parent subdivision constraint
SubdivisionSearchRequest hierarchyRequest = new()
{
    Query = "Beirut",
    CountryCode = "LB",
    ParentSubdivisionCode = "BA" // Must be child of Beirut Amiounieh
};
SubdivisionSearchResult? result = client.Subdivisions.Search(hierarchyRequest);

Time Zones

Get all time zones

List<TimeZoneInfo> timeZones = client.TimeZones.Get();

Get time zones by IDs

string[] timeZoneIds = ["Hawaiian Standard Time", "Middle East Standard Time", "Greenland Standard Time"];
List<TimeZoneInfo> timeZones = client.TimeZones.Get(timeZoneIds);

Get time zones by country code

List<CountryTimeZone> timeZones = client.TimeZones.GetByCountry("LB");

Get current time in a time zone

string toTimeZone = "Eastern Standard Time";
DateTime convertedTime = client.TimeZones.GetTime(toTimeZone);

Convert UTC to a time zone

string toTimeZone = "Eastern Standard Time";
DateTime utcTime = DateTime.Parse("2022-11-09 10:00:00 AM");
DateTime convertedTime = client.TimeZones.GetTime(toTimeZone, utcTime);

Convert between time zones

string toTimeZone = "Afghanistan Standard Time";
string fromTimeZone = "Middle East Standard Time";
DateTime timeToConvert = DateTime.Parse("2022-11-08 12:00:00 PM");
DateTime convertedTime = client.TimeZones.GetTime(toTimeZone, timeToConvert, fromTimeZone);

Money

Add money

// Positive addition
Money moneyA = new("USD", 1.2m);
Money moneyB = new("USD", 1.4m);
Money sum = moneyA.Add(moneyB); // 2.6m

// Negative addition
Money negativeA = new("USD", -1.2m);
Money negativeB = new("USD", -1.4m);
Money negativeSum = negativeA.Add(negativeB); // -2.6m

Subtract money

// Positive subtraction
Money moneyA = new("USD", 1.2m);
Money moneyB = new("USD", 1.4m);
Money difference = moneyA.Subtract(moneyB); // -0.2m

// Negative subtraction
Money negativeA = new("USD", -1.2m);
Money negativeB = new("USD", -1.4m);
Money negativeDifference = negativeA.Subtract(negativeB); // 0.2m

Get decimal part of money as an integer

// Positive number
Money money = new("USD", 50.3m);
int decimalPart = money.DecimalNumberAsInteger; // 3

// Negative number
Money negativeMoney = new("USD", -50.3m);
int negativeDecimalPart = negativeMoney.DecimalNumberAsInteger; // -3

Phone Numbers

Get country code from an international phone number

PhoneNumber number = client.PhoneNumbers.Get("+16265895784");
string countryCode = number?.CountryCode;
// US

Get country calling code from an international phone number

PhoneNumber number = client.PhoneNumbers.Get("+16265895784");
string countryCallingCode = number?.CountryCallingCode;
// 1

Get local number from an international phone number

PhoneNumber number = client.PhoneNumbers.Get("+16265895784");
string localNumber = number?.Number;
// 6265895784

Validate phone number

bool isValid = client.PhoneNumbers.IsValidPhoneNumber("+16265895784");
// true

bool isValid = client.PhoneNumbers.IsValidPhoneNumber("invalid");
// false

Angry Monkey Cloud

This project is part of the Angry Monkey Cloud open-source ecosystem. Follow the shared AI development instructions and browse the project catalog and GitHub organization.