
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.
All artifacts are published to Maven Central, so make sure it is listed in your repositories:
repositories {
mavenCentral()
}Then add the dependencies:
dependencies {
implementation("org.kimplify:countries-core:0.2.0")
// Optional: Multilingual support (14 languages)
implementation("org.kimplify:countries-i18n:0.2.0")
}In a KMP project, add the dependencies to the commonMain source set — a single dependency covers all targets (Android, iOS, JVM, JS, WASM):
kotlin {
sourceSets {
commonMain.dependencies {
implementation("org.kimplify:countries-core:0.2.0")
implementation("org.kimplify:countries-i18n:0.2.0") // optional
}
}
}If you use a version catalog, add to gradle/libs.versions.toml:
[versions]
kcountries = "0.2.0"
[libraries]
kcountries-core = { module = "org.kimplify:countries-core", version.ref = "kcountries" }
kcountries-i18n = { module = "org.kimplify:countries-i18n", version.ref = "kcountries" }dependencies {
implementation(libs.kcountries.core)
implementation(libs.kcountries.i18n) // optional
}Everything lives under the org.kimplify.countries package. The examples below include the imports they need.
import org.kimplify.countries.Countries
import org.kimplify.countries.model.Alpha2Code
import org.kimplify.countries.model.Alpha3Code
import org.kimplify.countries.model.NumericCode
// 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")import org.kimplify.countries.Countries
import org.kimplify.countries.model.Continent
import org.kimplify.countries.model.Region
// 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")
}import org.kimplify.countries.extensions.*
// 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")
)// Extension functions for easy access
country.getDisplayName() // Returns displayName or falls back to name
country.getNativeName() // Returns native or falls back to displayName/nameAll codes are wrapped in inline value classes for type safety with zero runtime overhead:
Alpha2Code: 2-letter country codeAlpha3Code: 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")Continent: 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)
}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
}@CountriesDsl
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
}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).
import org.kimplify.countries.i18n.Locale
import org.kimplify.countries.i18n.extensions.getLocalizedName
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")Supported Languages:
See countries-i18n/README.md for full documentation.
[Add your license here]
[Add contribution guidelines]
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.
All artifacts are published to Maven Central, so make sure it is listed in your repositories:
repositories {
mavenCentral()
}Then add the dependencies:
dependencies {
implementation("org.kimplify:countries-core:0.2.0")
// Optional: Multilingual support (14 languages)
implementation("org.kimplify:countries-i18n:0.2.0")
}In a KMP project, add the dependencies to the commonMain source set — a single dependency covers all targets (Android, iOS, JVM, JS, WASM):
kotlin {
sourceSets {
commonMain.dependencies {
implementation("org.kimplify:countries-core:0.2.0")
implementation("org.kimplify:countries-i18n:0.2.0") // optional
}
}
}If you use a version catalog, add to gradle/libs.versions.toml:
[versions]
kcountries = "0.2.0"
[libraries]
kcountries-core = { module = "org.kimplify:countries-core", version.ref = "kcountries" }
kcountries-i18n = { module = "org.kimplify:countries-i18n", version.ref = "kcountries" }dependencies {
implementation(libs.kcountries.core)
implementation(libs.kcountries.i18n) // optional
}Everything lives under the org.kimplify.countries package. The examples below include the imports they need.
import org.kimplify.countries.Countries
import org.kimplify.countries.model.Alpha2Code
import org.kimplify.countries.model.Alpha3Code
import org.kimplify.countries.model.NumericCode
// 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")import org.kimplify.countries.Countries
import org.kimplify.countries.model.Continent
import org.kimplify.countries.model.Region
// 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")
}import org.kimplify.countries.extensions.*
// 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")
)// Extension functions for easy access
country.getDisplayName() // Returns displayName or falls back to name
country.getNativeName() // Returns native or falls back to displayName/nameAll codes are wrapped in inline value classes for type safety with zero runtime overhead:
Alpha2Code: 2-letter country codeAlpha3Code: 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")Continent: 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)
}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
}@CountriesDsl
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
}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).
import org.kimplify.countries.i18n.Locale
import org.kimplify.countries.i18n.extensions.getLocalizedName
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")Supported Languages:
See countries-i18n/README.md for full documentation.
[Add your license here]
[Add contribution guidelines]