🗺️ go‑countries

Go package providing comprehensive country data in all standard ISO formats

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

• Installation
• Usage
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Credits
• Maintainers
• Contributing
• License

📦 Installation

go-countries requires a supported release of Go.

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

💡 Usage

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

```go 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:

bash cd /path/to/your/project

1. Run the go generate command:

bash 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

🧪 Examples & Tests

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

Run all tests (fast):

bash script make test

Run all tests with race detector (slower): bash script make test-race

⚡ Benchmarks

Run the Go benchmarks:

bash script make 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 Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

🙏 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 :raisedhands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speechballoon:. You can also support this project by becoming a sponsor on GitHub :clap: or by making a bitcoin donation to ensure this journey continues indefinitely! :rocket:

📝 License