BeamLabCountries is a collection of all sorts of useful information for every country in the ISO 3166 standard. It includes country data, subdivisions (states/provinces), international organizations, language information, and country name translations.
It is based on the data from the pretty popular but abandoned Elixir library Countries and previously the Ruby Gem Countries.
defpdepsdo[{:beamlab_countries,"~> 1.0"}]endAfter you are done, run mix deps.get in your shell to fetch and compile beamlab_countries.
Full documentation is available at HexDocs.
- BeamLabCountries - Main country API
- BeamLabCountries.Unions - International organizations
- BeamLabCountries.Languages - Languages and locales
- BeamLabCountries.Translations - Country name translations
- BeamLabCountries.Subdivisions - States/provinces
Get all countries:
countries=BeamLabCountries.all()Enum.count(countries)# 250Get a single country by alpha2 or alpha3 code:
country=BeamLabCountries.get("PL")# %BeamLabCountries.Country{name: "Poland", alpha2: "PL", alpha3: "POL", ...}country=BeamLabCountries.get_by_alpha3("DEU")# %BeamLabCountries.Country{name: "Germany", alpha2: "DE", alpha3: "DEU", ...}Filter countries by attribute:
# By regioncountries=BeamLabCountries.filter_by(:region,"Europe")Enum.count(countries)# 51# By currencyeurozone=BeamLabCountries.filter_by(:currency_code,"EUR")# By continentasian_countries=BeamLabCountries.filter_by(:continent,"Asia")# By EU membershipeu_countries=BeamLabCountries.filter_by(:eu_member,true)# By language (countries where English is spoken)english_speaking=BeamLabCountries.filter_by(:languages_spoken,"en")Enum.count(english_speaking)# 167Check if a country exists:
BeamLabCountries.exists?(:name,"Poland")# trueBeamLabCountries.exists?(:alpha2,"XX")# falseGet subdivisions (states, provinces, regions) for a country:
country=BeamLabCountries.get("BR")subdivisions=BeamLabCountries.Subdivisions.all(country)Enum.count(subdivisions)# 27# Each subdivision includes id, name, translations, and geo datahd(subdivisions)# %BeamLabCountries.Subdivision{id: "AC", name: "Acre", ...}Query international organizations and their member countries:
aliasBeamLabCountries.Unions# Get all unionsUnions.all()# Returns 13 unions: EU, NATO, G7, G20, ASEAN, OPEC, OECD, APEC, Mercosur, USMCA, African Union, EEA, EFTA# Get a specific unioneu=Unions.get("eu")# %BeamLabCountries.Union{code: "eu", name: "European Union", type: :economic_political, ...}# Check union membershipUnions.member?("DE","eu")# trueUnions.member?("US","nato")# true# Get all unions a country belongs toUnions.for_country("DE")# [%Union{code: "eu", ...}, %Union{code: "nato", ...}, %Union{code: "g7", ...}, ...]Unions.codes_for_country("DE")# ["eu", "eea", "nato", "g7", "g20", "oecd"]# Get all member countries of a unioneu_countries=Unions.member_countries("eu")Enum.count(eu_countries)# 27# Filter unions by typemilitary_unions=Unions.filter_by(:type,:military)# [%Union{code: "nato", name: "North Atlantic Treaty Organization", ...}]Look up language information by ISO 639-1 code:
aliasBeamLabCountries.Languages# Get language nameLanguages.get_name("de")# "German"Languages.get_name("ja")# "Japanese"# Get native language nameLanguages.get_native_name("de")# "Deutsch"Languages.get_native_name("zh")# "中文"# Get full language info as structLanguages.get("fr")# %BeamLabCountries.Language{code: "fr", name: "French", native_name: "Français", family: "Indo-European"}# Get all languagesLanguages.all()# [%Language{code: "aa", name: "Afar", ...}, ...]Languages.count()# 184# Check if a language code is validLanguages.valid?("en")# trueWork with regional language variants (e.g., "en-US", "es-MX", "pt-BR"):
aliasBeamLabCountries.Languages# Get a locale with full details including flag and country namelocale=Languages.get_locale("en-US")# %BeamLabCountries.Locale{# code: "en-US",# base_code: "en",# region_code: "US",# name: "English (United States)",# native_name: "English (US)",# flag: "🇺🇸",# country_name: "United States of America"# }# Get all localesLanguages.all_locales()# Returns 140 locales sorted by nameLanguages.locale_count()# 140# Get all regional variants for a languageLanguages.locales_for_language("en")# [%Locale{code: "en-AU", ...}, %Locale{code: "en-CA", ...}, %Locale{code: "en-GB", ...}, %Locale{code: "en-US", ...}]Languages.locales_for_language("es")# [%Locale{code: "es-AR", ...}, %Locale{code: "es-ES", ...}, %Locale{code: "es-MX", ...}, ...]# Parse a locale codeLanguages.parse_locale("pt-BR")# {"pt", "BR"}# Check if a locale is validLanguages.valid_locale?("en-US")# trueFind countries where a language is spoken:
aliasBeamLabCountries.Languages# Get all countries where English is spokencountries=Languages.countries_for_language("en")length(countries)# 167# Get just the country namesLanguages.country_names_for_language("es")# ["Argentina", "Bolivia", "Chile", "Colombia", "Costa Rica", "Cuba", ...]# Get flags for countries where a language is spokenLanguages.flags_for_language("fr")# ["🇧🇪", "🇧🇫", "🇧🇮", "🇧🇯", "🇨🇦", "🇨🇩", "🇨🇫", "🇨🇬", "🇨🇭", "🇨🇮", "🇨🇲", "🇫🇷", ...]Get country names in different languages:
aliasBeamLabCountries.Translations# Get country name in a specific languageTranslations.get_name("DE","fr")# "Allemagne"Translations.get_name("JP","de")# "Japan"Translations.get_name("US","zh")# "美国"Translations.get_name("FR","ar")# "فرنسا"# Get country name in all supported languagesTranslations.get_all_names("IT")# %{"ar" => "إيطاليا", "de" => "Italien", "en" => "Italy", "es" => "Italia",# "fr" => "Italie", "ja" => "イタリア", "ko" => "이탈리아", ...}# Check supported localesTranslations.supported_locales()# ["ar", "de", "en", "es", "et", "fr", "it", "ja", "ko", "nl", "pl", "pt", "ru", "sv", "uk", "zh"]Translations.locale_supported?("ja")# true- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Copyright (c) 2025 Dmitri Don / BeamLab
Copyright (c) 2015-2025 Sebastian Szturo
This software is licensed under the MIT license.