BeamLabCountries.Cities (beamlab_countries v2.0.1)

Major cities by country, with populations, coordinates, time zones and translated names.

For each covered country the data holds up to ten largest populated places (using GeoNames populations) plus the capital when GeoNames identifies one. Places near a larger place in the same country (closer than 12 km) are left out. The United States adds at least ten places per state, and Canada adds at least ten per province or territory, including smaller towns and villages where needed. Each of those cities carries its subdivision ID, see BeamLabCountries.Subdivisions. Washington D.C. is included as the US capital and is not padded out with District neighbourhoods.

Quality is best for large countries; for very small territories GeoNames only knows villages and parishes, which is what you get.

Names

name is the preferred English name, falling back to GeoNames' primary name; native_name is the name in the first official language with usable data, and translations holds the other locales supported by BeamLabCountries.Translations:

iex> vienna = BeamLabCountries.Cities.capital("AT")
iex> {vienna.name, vienna.native_name}
{"Vienna", "Wien"}
iex> BeamLabCountries.Cities.get_name(vienna, "fr")
"Vienne"

Data is loaded at compile time. It comes from GeoNames, licensed under CC BY 4.0.

Summary

Functions

all()

Returns all cities, largest first.

capital(country_code)

Returns the capital recorded by GeoNames, or nil if none is identified.

count()

Returns the total number of cities.

for_country(country, opts \\ [])

Returns the largest cities of a country, largest first.

for_subdivision(country, subdivision_id, opts \\ [])

Returns the largest cities of a subdivision, largest first.

get(id)

Returns a city by its GeoNames ID, or nil if not found.

get_name(city, locale)

Returns the name of a city in the given locale.

Functions

all()

@spec all() :: [BeamLabCountries.City.t()]

Returns all cities, largest first.

Examples

iex> BeamLabCountries.Cities.all() |> hd() |> Map.get(:name)
"Shanghai"

capital(country_code)

@spec capital(BeamLabCountries.Country.t() | String.t()) ::
  BeamLabCountries.City.t() | nil

Returns the capital recorded by GeoNames, or nil if none is identified.

Accepts a BeamLabCountries.Country struct or an alpha2 code.

Examples

iex> BeamLabCountries.Cities.capital("EE").name
"Tallinn"

iex> BeamLabCountries.Cities.capital("XX")
nil

count()

@spec count() :: non_neg_integer()

Returns the total number of cities.

Examples

iex> BeamLabCountries.Cities.count() > 2000
true

for_country(country, opts \\ [])

@spec for_country(BeamLabCountries.Country.t() | String.t(), keyword()) :: [
  BeamLabCountries.City.t()
]

Returns the largest cities of a country, largest first.

Accepts a BeamLabCountries.Country struct or an alpha2 code (case-insensitive). Returns an empty list for unknown countries and countries without data.

Options

:limit - maximum number of cities, or :all for everything in the data. When omitted, the result is the 10 largest cities, plus the capital when it ranks lower than that. The default matters for the United States and Canada, which also contain the largest cities of each state or province. An explicit limit is a hard cap and can leave the capital out. Raises ArgumentError unless the limit is a non-negative integer or :all.

Examples

iex> BeamLabCountries.Cities.for_country("EE") |> Enum.take(3) |> Enum.map(& &1.name)
["Tallinn", "Tartu", "Narva"]

iex> BeamLabCountries.Cities.for_country("us", limit: 3) |> Enum.map(& &1.name)
["New York", "Los Angeles", "Chicago"]

iex> BeamLabCountries.Cities.capital("IN") in BeamLabCountries.Cities.for_country("IN")
true

iex> BeamLabCountries.Cities.for_country("XX")
[]

for_subdivision(country, subdivision_id, opts \\ [])

@spec for_subdivision(
  BeamLabCountries.Country.t() | String.t(),
  String.t(),
  keyword()
) :: [
  BeamLabCountries.City.t()
]

Returns the largest cities of a subdivision, largest first.

Only the United States and Canada have subdivision data. Accepts a BeamLabCountries.Country struct or an alpha2 code; both the country code and the subdivision ID are case-insensitive. Takes the same :limit option as for_country/2 (default: :all). All 50 US states and all 13 Canadian provinces and territories have at least ten entries. Use limit: 10 to get their ten largest places.

Examples

iex> BeamLabCountries.Cities.for_subdivision("US", "CA") |> hd() |> Map.get(:name)
"Los Angeles"

iex> BeamLabCountries.Cities.for_subdivision("ca", "on", limit: 1) |> Enum.map(& &1.name)
["Toronto"]

iex> length(BeamLabCountries.Cities.for_subdivision("CA", "PE", limit: 10))
10

iex> BeamLabCountries.Cities.for_subdivision("DE", "BY")
[]

get(id)

@spec get(integer()) :: BeamLabCountries.City.t() | nil

Returns a city by its GeoNames ID, or nil if not found.

Examples

iex> BeamLabCountries.Cities.get(2761369).name
"Vienna"

iex> BeamLabCountries.Cities.get(1)
nil

get_name(city, locale)

@spec get_name(BeamLabCountries.City.t(), String.t()) :: String.t()

Returns the name of a city in the given locale.

Locales are those of BeamLabCountries.Translations.supported_locales/0; they are case-insensitive and regional codes are reduced to their language ("de-AT" becomes "de"). Falls back to the English name when there is no translation, which also means the locale's name is the same as the English one. English locales always use the canonical name from the generated data.

Examples

iex> munich = BeamLabCountries.Cities.get(2867714)
iex> BeamLabCountries.Cities.get_name(munich, "de")
"München"
iex> BeamLabCountries.Cities.get_name(munich, "ru")
"Мюнхен"
iex> BeamLabCountries.Cities.get_name(munich, "xx")
"Munich"