🗺️  go-countries

Go package providing comprehensive country data in all standard ISO formats.

CI / CD		Quality
Security		Community

Project Navigation

🚀 Installation	🧪 Examples & Tests	📚 Documentation
🤝 Contributing	🛠️ Code Standards	⚡ Benchmarks
🤖 AI Usage	⚖️ License	👥 Maintainers

📦 Installation

go-countries requires a supported release of Go.

go get -u github.com/mrz1836/go-countries

💡 Usage

Here is a basic example of how to use go-countries in your Go project:

package main

import (
    "fmt"
    "github.com/mrz1836/go-countries"
)

func main() {
    country := countries.GetByAlpha2(countries.Alpha2US)
    if country != nil {
        fmt.Printf("Country: %s, Capital: %s\n", country.Name, country.Capital)
    } else {
        fmt.Println("Country not found")
    }
}

• Explore additional usage examples for practical integration patterns
• Review benchmark results to assess performance characteristics
• Examine the comprehensive test suite for validation and coverage
• Inspect the code generator for details on data sources and the build process

📚 Documentation

View the generated documentation

Heads up! go-countries is intentionally light on dependencies. The only external package it uses is the excellent testify suite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.

Features

• Comprehensive list of all recognized countries, provided as a Go slice of structs for easy access and manipulation
• Direct access to raw country and currency JSON data in the data package for custom processing or validation
• Zero init() overhead—just import and use the countries package without side effects
• Fast, allocation-free lookups for all retrieval functions, ensuring optimal performance in production environments
• Includes region, subregion, capital, and currency information for each country
• Designed for extensibility—add or update country data via code generation from JSON sources
• Well-documented, tested, and benchmarked for reliability and speed

Functions

• GetAll(): Retrieve the entire slice of all known countries, including metadata such as names, codes, regions, capitals, and currencies
• GetByAlpha2(countries.Alpha2US): Find a country by its ISO 3166-1 alpha-2 code
• GetByAlpha3(countries.Alpha3USA): Retrieve a country by its ISO 3166-1 alpha-3 code
• GetByCapital("Washington"): Find a country by its capital city in a case-insensitive search
• GetByCountryCode("840"): Lookup by ISO 3166 numeric country code, supporting string or integer input
• GetByISO31662("ISO 3166-2:US"): Retrieve a country by its ISO 3166-2 subdivision code
• GetByName("United States of America"): Lookup a country by its official name, supporting case-insensitive queries

Code Generation

If you need to update the country data or regenerate the Go code, you can use the go generate command. This will read the JSON data files and generate a Go file containing all the country data in a structured format.

To generate the Go code for the country data, follow these steps:

1. Navigate to the project root directory:

   cd /path/to/your/project

2. Run the go generate command:

   go generate -x ./generate/...

This command executes the code generation logic defined in the generate.go file located in the /generate/ directory. The generated code is written to countries_data.go in the project directory.

Additional Documentation & Repository Management

Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump bump=patch push=true branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.22.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64):

Function	Ops/sec (approx)	Time per op	Allocations	Bytes Allocated
GetAll	5,263,413	225.4 ns	1	2,048 B
GetByAlpha2	100,000,000	10.36 ns	0	0 B
GetByAlpha3	100,000,000	10.97 ns	0	0 B
GetByCapital	33,426,183	35.19 ns	1	16 B
GetByCountryCode	100,467,049	11.10 ns	0	0 B
GetByISO31662	59,682,316	20.16 ns	0	0 B
GetByName	46,466,527	25.66 ns	0	0 B

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments.

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with AI assistants.

🙏 Credits

Used: ISO-3166-Countries-with-Regional-Codes Used: List of Countries & Currencies

👥 Maintainers

MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

📝 License