Lightweight, high-performance country dataset embedding ISO 3166-1 codes, names and flag emojis; type-safe code wrappers, O(1) lookups, expressive DSL queries, tiny binary footprint.
A lightweight, high-performance Kotlin Multiplatform library providing ISO 3166-1 country data with native names and multilingual support across Android, iOS, JVM, JavaScript and WebAssembly.
dependencies {
implementation("org.kimplify:countries-core:0.1.1")
// Optional: Multilingual support (14 languages)
implementation("org.kimplify:countries-i18n:0.1.1")
}
// Get all countries
val allCountries = Countries.repository.getAll()
// Find by code
val usa = Countries.repository.findByAlpha2(Alpha2Code("US"))
val uk = Countries.repository.findByAlpha3(Alpha3Code("GBR"))
val france = Countries.repository.findByNumeric(NumericCode("250"))
// Search by name (searches across display, native, and formal names)
val results = Countries.repository.searchByName("United")
// Extension functions for easy access
country.getDisplayName() // Returns displayName or falls back to name
country.getNativeName() // Returns native or falls back to displayName/name
All codes are wrapped in inline value classes for type safety with zero runtime overhead:
Alpha2Code: 2-letter country codeContinent: 7 continents (AFRICA, ANTARCTICA, ASIA, EUROPE, NORTH_AMERICA, OCEANIA, SOUTH_AMERICA)Region: 23 UN geoscheme regions (CARIBBEAN, EASTERN_EUROPE, SOUTHEASTERN_ASIA, etc.)object Countries {
val repository: CountriesRepository // Main data access point
val VERSION: String // Library version (auto-generated from catalog)
const val TOTAL_COUNTRIES: Int // Total countries (249)
}
Country data is embedded as Kotlin code for maximum performance:
Single implementation works on all platforms:
No platform-specific code needed!
Semantic versioning: MAJOR.MINOR.PATCH
Optional module providing country name translations in 13 languages (+ English fallback).
Supported Languages:
See countries-i18n/README.md for full documentation.
[Add your license here]
[Add contribution guidelines]
// Single filter
val usa = Countries.repository.query {
alpha2("US")
}.firstOrNull()
// Name search
val unitedCountries = Countries.repository.query {
nameContains("United")
}.toList()
// OR logic
val northAmericans = Countries.repository.query {
or {
alpha2("US")
alpha2("CA")
alpha2("MX")
}
}.toList()
// Filter by continent, region, calling code, currency, timezone
val europeanCountries = Countries.repository.query {
continent(Continent.EUROPE)
}.toList()
val westernEurope = Countries.repository.query {
region(Region.WESTERN_EUROPE)
}.toList()
// NOT logic
val nonEuropean = Countries.repository.query {
not { continent(Continent.EUROPE) }
}.toList()
// Iterate directly (CountriesQueryResult implements Iterable)
for (country in Countries.repository.query { currency("EUR") }) {
println("${country.getDisplayName()} uses EUR")
}
// Convert code to country
val usa = "US".toCountry()
val france = "FRA".toCountry()
val germany = "276".toCountry()
// Get properties
val flag = "US".flagEmoji // "🇺🇸"
val displayName = "US".displayCountryName // "United States"
val nativeName = "JP".nativeCountryName // "日本"
// Convert between formats
val alpha3 = "US".toAlpha3 // "USA"
val alpha2 = "USA".toAlpha2 // "US"
// Access metadata via toCountry()
val country = "US".toCountry()!!
val code = country.callingCode // CallingCode("+1")
val curr = country.currency // CurrencyCode("USD")
val cont = country.continent // Continent.NORTH_AMERICA
val reg = country.region // Region.NORTHERN_AMERICA
val tz = country.timezone // TimezoneId("America/New_York")
data class Country(
val alpha2: Alpha2Code, // ISO 3166-1 alpha-2 (e.g., "US")
val alpha3: Alpha3Code, // ISO 3166-1 alpha-3 (e.g., "USA")
val numeric: NumericCode, // ISO 3166-1 numeric (e.g., "840")
val name: CountryName, // Formal ISO name (e.g., "United States of America (the)")
val flag: FlagEmoji, // Flag emoji (e.g., "🇺🇸")
val displayName: String?, // User-friendly name (e.g., "United States")
val native: String?, // Native language name (e.g., "日本")
val continent: Continent, // Geographic continent (e.g., NORTH_AMERICA)
val region: Region, // UN geoscheme region (e.g., NORTHERN_AMERICA)
val callingCode: CallingCode, // E.164 calling code (e.g., "+1")
val currency: CurrencyCode, // ISO 4217 currency (e.g., "USD")
val timezone: TimezoneId // IANA timezone (e.g., "America/New_York")
)
Alpha3Code: 3-letter country codeNumericCode: 3-digit country codeCountryName: Country name stringFlagEmoji: Flag emoji (validated via Unicode codepoints)CallingCode: E.164 calling code (e.g., "+1", "+44")CurrencyCode: ISO 4217 currency code (e.g., "USD", "EUR")TimezoneId: IANA timezone identifier (e.g., "America/New_York")interface CountriesRepository {
fun getAll(): List<Country>
fun findByAlpha2(code: Alpha2Code): Country?
fun findByAlpha3(code: Alpha3Code): Country?
fun findByNumeric(code: NumericCode): Country?
fun searchByName(query: String): List<Country>
fun getByContinent(continent: Continent): List<Country>
fun getByRegion(region: Region): List<Country>
fun getByCallingCode(callingCode: CallingCode): List<Country>
fun getByCurrency(currencyCode: CurrencyCode): List<Country>
fun query(block: CountriesQuery.() -> Unit): CountriesQueryResult
}
class CountriesQuery {
fun alpha2(code: String)
fun alpha3(code: String)
fun numeric(code: String)
fun nameContains(text: String)
fun nameEquals(name: String)
fun nameStartsWith(prefix: String)
fun continent(continent: Continent)
fun region(region: Region)
fun callingCode(code: String)
fun currency(code: String)
fun timezone(id: String)
fun or(block: CountriesQuery.() -> Unit)
fun not(block: CountriesQuery.() -> Unit)
}
class CountriesQueryResult : Iterable<Country> {
fun firstOrNull(): Country?
fun first(): Country
fun toList(): List<Country>
fun count(): Int
fun isEmpty(): Boolean
fun isNotEmpty(): Boolean
}
val country = Countries.repository.findByAlpha2(Alpha2Code("JP"))!!
country.getLocalizedName(Locale.EN) // "Japan"
country.getLocalizedName(Locale.ES) // "Japón"
country.getLocalizedName(Locale.FR) // "Japon"
country.getLocalizedName(Locale.DE) // "Japan"
country.getLocalizedName(Locale.AR) // "اليابان"
country.getLocalizedName(Locale.ZH) // "日本"
country.getLocalizedName(Locale.RU) // "Япония"
country.getLocalizedName(Locale.JA) // "日本"
country.getLocalizedName(Locale.PT) // "Japão"
country.getLocalizedName(Locale.KO) // "일본"
country.getLocalizedName(Locale.IT) // "Giappone"
country.getLocalizedName(Locale.TR) // "Japonya"
country.getLocalizedName(Locale.HI) // "जापान"
country.getLocalizedName(Locale.ID) // "Jepang"
// Locale strings are normalized automatically
country.getLocalizedName("es-MX") // "Japón" (extracts "es")
country.getLocalizedName("PT_BR") // "Japão" (extracts "pt")
Surfaced from shared tags and platforms — no rankings paid for.