worldwide 🗺️

A typed database of world countries for Gleam - currencies, languages, calling codes, timezones - sourced from countries.dev. worldwide itself ships no data: you generate your own copy into your project, own it in your repo, and refresh it whenever you like, independent of the worldwide version you depend on.

Install

gleam add worldwide

gleam add worldwide succeeds immediately - it’s just a dependency. But worldwide.all() (and any other lookup) will panic the first time you actually call it until you’ve generated the data:

gleam run -m worldwide/pull_countries

This writes data/worldwide_countries.json to your project root. Commit it to your own repo - it belongs to your project, not to worldwide. This way, you keep your data and don’t rely on third-parties beyond when you want to update the data.

Usage

import worldwide
import worldwide/country
import worldwide/region.{Europe}

pub fn main() {
  // Every country
  let everything = worldwide.all()

  // Look up by alpha-2, alpha-3 or numeric code (case-insensitive)
  let assert Ok(spain) = country.from_iso_code("ES")
  spain.name        // "Spain"
  spain.currencies  // [Currency("EUR", "Euro", "€")]

  // Or look up by alpha-2 specifically
  let assert Ok(japan) = country.from_alpha2("JP")

  // Exact common English-name lookup
  let assert Ok(japan_by_name) = country.from_name("Japan")

  // Filter by region, currency, language, calling code, or timezone
  everything
  |> worldwide.filter_by(worldwide.Region(Europe))
}

Country lookup helpers live in worldwide/country; worldwide re-exports all() and adds filter_by, currencies, languages, timezones, regions, and subregions on top.

Refreshing the data

Re-run the same command any time you want newer data (new countries, currency redenominations, disputed-territory changes, etc.) - it always re-fetches from countries.dev and overwrites your generated file:

gleam run -m worldwide/pull_countries

To check whether your generated file is stale without overwriting it - useful as a CI step - run:

gleam run -m worldwide/pull_countries check

This exits non-zero and reports if a fresh fetch would produce a different file.

Notes

• Lookups read data/worldwide_countries.json the first time they’re called and cache the result for the lifetime of the program - no repeated file I/O or network calls after that.
• Both the generator and the runtime lookups compile for the Erlang and JavaScript (Node) targets.
• The generator (and the runtime loader) find your project root by walking up from the current directory to the nearest gleam.toml, so they work correctly even from a subdirectory.
• If you call worldwide.all() (or any lookup) before ever running the generator, it panics with the exact command to run.