Place is an Elixir library and dataset containing names, ISO 3166 codes, currencies and much more about countries, states and cities around the world. It's using the countries-states-cities-database project as the data source, and it's regularly updated with new data.

iex> Place.get_country(country_code: "US")
%Place.Country{
  capital: "Washington",
  csc_id: 233,
  csc_region_id: "2",
  csc_subregion_id: "6",
  currency: "USD",
  currency_name: "United States dollar",
  currency_symbol: "$",
  emoji: "🇺🇸",
  emojiU: "U+1F1FA U+1F1F8",
  iso2: "US",
  iso3: "USA",
  latitude: "38.00000000",
  longitude: "-97.00000000",
  name: "United States",
  nationality: "American",
  native: "United States",
  numeric_code: "840",
  phone_code: "1",
  ... # and more
}

Add :place to your mix.exs:

{:place, "~> 0.1"}

Add Place to your application's supervisor (read more under usage for an alternative approach):

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    ...,
    Place
  ]

  Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
end

Place provides functions for getting countries, states and cities. The documentation for the Place module contains detailed information about each function, but here are a few examples:

Get a list of all countries:

iex> Place.get_countries() |> Enum.count()
250

Get all states in a country:

iex> Place.get_states(country_code: "US") |> Enum.count()
66 # The extra 16 are non-state US territories, which can be identified by the `type` field.

Get all cities in a state:

iex> Place.get_cities(country_code: "US", state_code: "CA") |> Enum.count()
1124

Get a country:

iex> Place.get_country(country_code: "US")
%Place.Country{
  ...,
  name: "United States",
  ...
}

Get a state:

iex> Place.get_state(country_code: "US", state_code: "CA")
%Place.State{
  ...,
  name: "California",
  ...
}

Get a city:

iex> Place.get_city(country_code: "US", state_code: "CA", city_name: "Los Angeles")
%Place.City{
  ...,
  name: "Los Angeles",
  ...
}

Place ships with a compressed database file, containing the countries-states-cities-database dataset. The Place module is a GenServer that at startup reads the file and holds it as state in a %Place.DB{} struct. This is convenient, since you don't have to think about passing around the struct, and for most use cases the overhead of the interprocess communication is negligible.

However, if you don't want to add Place to your application's supervisor or if want to directly access the %Place.DB{} struct, you can use Place.load_csc_db!(). Most of the functions in Place's API ships with two arities, one that assumes the GenServer is running and one that explicitly takes a %Place.DB{}. For example:

iex> Place.get_countries() # First option
iex> Place.load_csc_db!() |> Place.get_countries() # Second option

Place is released under the MIT license and the database file is released under the ODbL-1.0 license. See the LICENSE and priv/countries-states-cities-database/LICENSE files respectively for more information.