A simple list of countries for scala projects.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jens Grassel b82ef37675 Update README 1 month ago
project Update sbt to 1.4.4 1 month ago
src Update cats to 2.2.0 3 months ago
.gitignore Update sbt to 1.4.1 2 months ago
.scalafmt.conf Initial commit 6 months ago
AUTHORS.md Initial commit 6 months ago
CHANGELOG.md Update cats to 2.2.0 3 months ago
CONTRIBUTING.md Contribution guide 6 months ago
LICENSE Initial commit 6 months ago
NOTICE Initial commit 6 months ago
README.md Update README 1 month ago
build.sbt Update cats to 2.3.0 1 month ago


A list of countries.


This library simply provides a list of countries as data models.

In case you need a basic country model or simply a list which should contain most (if not all) countries then we got you covered.

The basic model looks like this:

sealed abstract class Country(
  val alpha2: Alpha2CountryCode,
  val alpha3: Alpha3CountryCode,
  val name: CountryName,
  val nameOfficial: StateName,
  val numeric: NumericCountryCode,
  val tld: List[TopLevelDomain]


The following libraries are used and expected to be provided by your project:

  • Cats
  • Circe
  • Enumeratum
  • Refined


scala> import com.wegtam.countries._, eu.timepit.refined.auto._
scala> Country.values.headOption
res0: Option[com.wegtam.countries.Country] = Some(Afghanistan)
scala> Country.fromAlpha2("DE")
res1: Either[String,com.wegtam.countries.Country] = Right(Germany)
scala> Country.fromAlpha2("XX")
res2: Either[String,com.wegtam.countries.Country] = Left(No such country!)
scala> Country.fromAlpha3("ESH")
res3: Either[String,com.wegtam.countries.Country] = Right(WesternSahara)
scala> Country.fromNumeric("858")
res4: Either[String,com.wegtam.countries.Country] = Right(Uruguay)
scala> import codecs.circe.alpha2._, io.circe.syntax._
scala> Country.fromNumeric("858").map(_.asJson)
res5: scala.util.Either[String,io.circe.Json] = Right("UY")

Circe Codecs

Because quite often you need JSON, we provide several codecs. Please import the ones that you prefer. Currently three codecs are provided:

  1. decode / encode from / to the alpha-2 country code (codecs.circe.alpha2)
  2. decode / encode from / to the alpha-3 country code (codecs.circe.alpha3)
  3. decode / encode from / to the numeric country code (codecs.circe.numeric)

Please note that the "numeric" encoder will still produce strings because there are codec with leading zeros!

Getting started

Just add the bintray resolver to your build configuration to be able to include the library.

resolvers += "Wegtam-Free" at "https://dl.bintray.com/wegtam/free"
libraryDependencies += "com.wegtam" %% "countries" % VERSION

For development and testing you need to install sbt. Please see CONTRIBUTING.md for details how to to contribute to the project.