Specs

countries([atom()]) :: %{required(String.t()) => map()}

Returns a map of country codes and their full names. Takes in a list of optional atoms to tailor the results. For example, :with_subdivisions only includes countries with subdivisions.

iex> countries = ISO.countries()
iex> get_in(countries, ["US", "name"])
"United States of America (the)"
iex> get_in(countries, ["PR", "name"])
"Puerto Rico"

iex> countries = ISO.countries([:with_subdivisions])
iex> countries["PR"]
nil

iex> countries = ISO.countries([:exclude_territories])
iex> countries["PR"]
nil

Specs

country_code(String.t()) :: nil | country_code()

Converts a full country name to its 2-letter ISO-3166-2 code.

iex> ISO.country_code("United States")
"US"

iex> ISO.country_code("UNITED STATES")
"US"

iex> ISO.country_code("Mexico")
"MX"

iex> ISO.country_code("Venezuela")
"VE"

iex> ISO.country_code("Iran")
"IR"

iex> ISO.country_code("Taiwan")
"TW"

iex> ISO.country_code("Bolivia")
"BO"

iex> ISO.country_code("Not a country.")
nil

Specs

country_name(country_code(), nil | :informal | :short_name) :: nil | String.t()

Converts a country's 2-letter code to its full name.

iex> ISO.country_name("US")
"United States of America (the)"

iex> ISO.country_name("US", :informal)
"United States of America"

iex> ISO.country_name("US", :short_name)
"UNITED STATES OF AMERICA"

iex> ISO.country_name("TN")
"Tunisia"

iex> ISO.country_name("TX")
nil

Specs

data() :: %{required(country_code()) => map()}

Returns all ISO-3166-2 data.

Specs

find_country(country_code() | String.t()) :: nil | {country_code(), map()}

Finds the country data for the given country. May be an ISO-3166-compliant country code or a string to perform a search with. Return a tuple in the format {code, data} if a country was found; otherwise nil.

iex> {code, data} = ISO.find_country("United States")
iex> code
"US"
iex> data |> Map.get("short_name")
"UNITED STATES OF AMERICA"

iex> {code, data} = ISO.find_country("US")
iex> code
"US"
iex> data |> Map.get("short_name")
"UNITED STATES OF AMERICA"

iex> ISO.find_country("Invalid")
nil

Specs

find_subdivision_code(country_code(), String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

Takes a country input and subdivision and returns the validated, ISO-3166-compliant subdivision code in a tuple.

iex> ISO.find_subdivision_code("US", "TX")
{:ok, "US-TX"}

iex> ISO.find_subdivision_code("US", "US-TX")
{:ok, "US-TX"}

iex> ISO.find_subdivision_code("US", "Texas")
{:ok, "US-TX"}

iex> ISO.find_subdivision_code("United States", "Texas")
{:ok, "US-TX"}

iex> ISO.find_subdivision_code("SomeCountry", "SG-SG")
{:error, "Invalid country: SomeCountry"}

iex> ISO.find_subdivision_code("SG", "SG-Invalid")
{:error, "Invalid subdivision 'SG-Invalid' for country: SG (SG)"}

Specs

get_subdivision(String.t()) ::
  {:ok, map()} | {:error, :invalid_country | :not_found}

Returns the subdivision data for the ISO-3166-compliant subdivision code.

iex> ISO.get_subdivision("US-TX")
{:ok, %{"category" => "state", "name" => "Texas"}}

iex> ISO.get_subdivision("MX-CMX")
{:ok, %{"category" => "federal entity", "name" => "Ciudad de México"}}

iex> ISO.get_subdivision("11-SG")
{:error, :not_found}

iex> ISO.get_subdivision("SG-Invalid")
{:error, :not_found}

iex> ISO.get_subdivision("Invalid")
{:error, :not_found}

Specs

subdivision_code(country_code(), String.t()) :: nil | String.t()

Converts a full subdivision name to its 2-letter ISO-3166-2 code. The country MUST be an ISO-compliant 2-letter country code.

iex> ISO.subdivision_code("US", "Texas")
"US-TX"

iex> ISO.subdivision_code("US", "US-TX")
"US-TX"

iex> ISO.subdivision_code("CA", "AlberTa")
"CA-AB"

iex> ISO.subdivision_code("MX", "Yucatán")
"MX-YUC"

iex> ISO.subdivision_code("MX", "Yucatan")
"MX-YUC"

iex> ISO.subdivision_code("IE", "Co. Wicklow")
"IE-WW"

iex> ISO.subdivision_code("MX", "Not a subdivision.")
nil

Specs

territory?(country_code()) :: boolean()

Returns true if the country with the given code is a territory of another country. This only applies to subdivisions that have their own country code.

iex> ISO.territory?("PR")
true

iex> ISO.territory?("US")
false

iex> ISO.territory?("TX")
false