countries

package module

v1.0.8 Latest Latest Go to latest Published: Feb 7, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mrz1836/go-countries

Links

Open Source Insights

README ¶

🗺️ 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:

Navigate to the project root directory:
```
cd /path/to/your/project
```
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

Documentation ¶

Overview ¶

Package countries is a complete go-ready list of countries in all standardized formats.

This package provides functionalities to retrieve country information based on various identifiers such as name, alpha-2 code, alpha-3 code, country code, and ISO 3166-2 code. It includes methods to get a country by these identifiers and to retrieve the entire list of countries.

The package is designed to be straightforward to use and integrate into Go projects, making it simple to work with country data in a standardized way.

If you have any suggestions or comments, please feel free to open an issue in this GitHub repository!

By @MrZ1836

Code generated by go generate; DO NOT EDIT. This file was generated by robots at https://github.com/mrz1836/go-countries

Examples ¶

GetAll
GetByAlpha2
GetByAlpha3
GetByCapital
GetByCountryCode
GetByISO31662
GetByName
GetByName (ShowAll)

Constants ¶

View Source

const (
	Alpha2AF = "AF"
	Alpha2AX = "AX"
	Alpha2AL = "AL"
	Alpha2DZ = "DZ"
	Alpha2AS = "AS"
	Alpha2AD = "AD"
	Alpha2AO = "AO"
	Alpha2AI = "AI"
	Alpha2AQ = "AQ"
	Alpha2AG = "AG"
	Alpha2AR = "AR"
	Alpha2AM = "AM"
	Alpha2AW = "AW"
	Alpha2AU = "AU"
	Alpha2AT = "AT"
	Alpha2AZ = "AZ"
	Alpha2BS = "BS"
	Alpha2BH = "BH"
	Alpha2BD = "BD"
	Alpha2BB = "BB"
	Alpha2BY = "BY"
	Alpha2BE = "BE"
	Alpha2BZ = "BZ"
	Alpha2BJ = "BJ"
	Alpha2BM = "BM"
	Alpha2BT = "BT"
	Alpha2BO = "BO"
	Alpha2BQ = "BQ"
	Alpha2BA = "BA"
	Alpha2BW = "BW"
	Alpha2BV = "BV"
	Alpha2BR = "BR"
	Alpha2IO = "IO"
	Alpha2BN = "BN"
	Alpha2BG = "BG"
	Alpha2BF = "BF"
	Alpha2BI = "BI"
	Alpha2CV = "CV"
	Alpha2KH = "KH"
	Alpha2CM = "CM"
	Alpha2CA = "CA"
	Alpha2KY = "KY"
	Alpha2CF = "CF"
	Alpha2TD = "TD"
	Alpha2CL = "CL"
	Alpha2CN = "CN"
	Alpha2CX = "CX"
	Alpha2CC = "CC"
	Alpha2CO = "CO"
	Alpha2KM = "KM"
	Alpha2CG = "CG"
	Alpha2CD = "CD"
	Alpha2CK = "CK"
	Alpha2CR = "CR"
	Alpha2CI = "CI"
	Alpha2HR = "HR"
	Alpha2CU = "CU"
	Alpha2CW = "CW"
	Alpha2CY = "CY"
	Alpha2CZ = "CZ"
	Alpha2DK = "DK"
	Alpha2DJ = "DJ"
	Alpha2DM = "DM"
	Alpha2DO = "DO"
	Alpha2EC = "EC"
	Alpha2EG = "EG"
	Alpha2SV = "SV"
	Alpha2GQ = "GQ"
	Alpha2ER = "ER"
	Alpha2EE = "EE"
	Alpha2SZ = "SZ"
	Alpha2ET = "ET"
	Alpha2FK = "FK"
	Alpha2FO = "FO"
	Alpha2FJ = "FJ"
	Alpha2FI = "FI"
	Alpha2FR = "FR"
	Alpha2GF = "GF"
	Alpha2PF = "PF"
	Alpha2TF = "TF"
	Alpha2GA = "GA"
	Alpha2GM = "GM"
	Alpha2GE = "GE"
	Alpha2DE = "DE"
	Alpha2GH = "GH"
	Alpha2GI = "GI"
	Alpha2GR = "GR"
	Alpha2GL = "GL"
	Alpha2GD = "GD"
	Alpha2GP = "GP"
	Alpha2GU = "GU"
	Alpha2GT = "GT"
	Alpha2GG = "GG"
	Alpha2GN = "GN"
	Alpha2GW = "GW"
	Alpha2GY = "GY"
	Alpha2HT = "HT"
	Alpha2HM = "HM"
	Alpha2VA = "VA"
	Alpha2HN = "HN"
	Alpha2HK = "HK"
	Alpha2HU = "HU"
	Alpha2IS = "IS"
	Alpha2IN = "IN"
	Alpha2ID = "ID"
	Alpha2IR = "IR"
	Alpha2IQ = "IQ"
	Alpha2IE = "IE"
	Alpha2IM = "IM"
	Alpha2IL = "IL"
	Alpha2IT = "IT"
	Alpha2JM = "JM"
	Alpha2JP = "JP"
	Alpha2JE = "JE"
	Alpha2JO = "JO"
	Alpha2KZ = "KZ"
	Alpha2KE = "KE"
	Alpha2KI = "KI"
	Alpha2KP = "KP"
	Alpha2KR = "KR"
	Alpha2KW = "KW"
	Alpha2KG = "KG"
	Alpha2LA = "LA"
	Alpha2LV = "LV"
	Alpha2LB = "LB"
	Alpha2LS = "LS"
	Alpha2LR = "LR"
	Alpha2LY = "LY"
	Alpha2LI = "LI"
	Alpha2LT = "LT"
	Alpha2LU = "LU"
	Alpha2MO = "MO"
	Alpha2MG = "MG"
	Alpha2MW = "MW"
	Alpha2MY = "MY"
	Alpha2MV = "MV"
	Alpha2ML = "ML"
	Alpha2MT = "MT"
	Alpha2MH = "MH"
	Alpha2MQ = "MQ"
	Alpha2MR = "MR"
	Alpha2MU = "MU"
	Alpha2YT = "YT"
	Alpha2MX = "MX"
	Alpha2FM = "FM"
	Alpha2MD = "MD"
	Alpha2MC = "MC"
	Alpha2MN = "MN"
	Alpha2ME = "ME"
	Alpha2MS = "MS"
	Alpha2MA = "MA"
	Alpha2MZ = "MZ"
	Alpha2MM = "MM"
	Alpha2NA = "NA"
	Alpha2NR = "NR"
	Alpha2NP = "NP"
	Alpha2NL = "NL"
	Alpha2NC = "NC"
	Alpha2NZ = "NZ"
	Alpha2NI = "NI"
	Alpha2NE = "NE"
	Alpha2NG = "NG"
	Alpha2NU = "NU"
	Alpha2NF = "NF"
	Alpha2MK = "MK"
	Alpha2MP = "MP"
	Alpha2NO = "NO"
	Alpha2OM = "OM"
	Alpha2PK = "PK"
	Alpha2PW = "PW"
	Alpha2PS = "PS"
	Alpha2PA = "PA"
	Alpha2PG = "PG"
	Alpha2PY = "PY"
	Alpha2PE = "PE"
	Alpha2PH = "PH"
	Alpha2PN = "PN"
	Alpha2PL = "PL"
	Alpha2PT = "PT"
	Alpha2PR = "PR"
	Alpha2QA = "QA"
	Alpha2RE = "RE"
	Alpha2RO = "RO"
	Alpha2RU = "RU"
	Alpha2RW = "RW"
	Alpha2BL = "BL"
	Alpha2SH = "SH"
	Alpha2KN = "KN"
	Alpha2LC = "LC"
	Alpha2MF = "MF"
	Alpha2PM = "PM"
	Alpha2VC = "VC"
	Alpha2WS = "WS"
	Alpha2SM = "SM"
	Alpha2ST = "ST"
	Alpha2SA = "SA"
	Alpha2SN = "SN"
	Alpha2RS = "RS"
	Alpha2SC = "SC"
	Alpha2SL = "SL"
	Alpha2SG = "SG"
	Alpha2SX = "SX"
	Alpha2SK = "SK"
	Alpha2SI = "SI"
	Alpha2SB = "SB"
	Alpha2SO = "SO"
	Alpha2ZA = "ZA"
	Alpha2GS = "GS"
	Alpha2SS = "SS"
	Alpha2ES = "ES"
	Alpha2LK = "LK"
	Alpha2SD = "SD"
	Alpha2SR = "SR"
	Alpha2SJ = "SJ"
	Alpha2SE = "SE"
	Alpha2CH = "CH"
	Alpha2SY = "SY"
	Alpha2TW = "TW"
	Alpha2TJ = "TJ"
	Alpha2TZ = "TZ"
	Alpha2TH = "TH"
	Alpha2TL = "TL"
	Alpha2TG = "TG"
	Alpha2TK = "TK"
	Alpha2TO = "TO"
	Alpha2TT = "TT"
	Alpha2TN = "TN"
	Alpha2TR = "TR"
	Alpha2TM = "TM"
	Alpha2TC = "TC"
	Alpha2TV = "TV"
	Alpha2UG = "UG"
	Alpha2UA = "UA"
	Alpha2AE = "AE"
	Alpha2GB = "GB"
	Alpha2US = "US"
	Alpha2UM = "UM"
	Alpha2UY = "UY"
	Alpha2UZ = "UZ"
	Alpha2VU = "VU"
	Alpha2VE = "VE"
	Alpha2VN = "VN"
	Alpha2VG = "VG"
	Alpha2VI = "VI"
	Alpha2WF = "WF"
	Alpha2EH = "EH"
	Alpha2YE = "YE"
	Alpha2ZM = "ZM"
	Alpha2ZW = "ZW"
)

Predefined ISO 3166-1 alpha-2 codes.

View Source

const (
	Alpha3AFG = "AFG"
	Alpha3ALA = "ALA"
	Alpha3ALB = "ALB"
	Alpha3DZA = "DZA"
	Alpha3ASM = "ASM"
	Alpha3AND = "AND"
	Alpha3AGO = "AGO"
	Alpha3AIA = "AIA"
	Alpha3ATA = "ATA"
	Alpha3ATG = "ATG"
	Alpha3ARG = "ARG"
	Alpha3ARM = "ARM"
	Alpha3ABW = "ABW"
	Alpha3AUS = "AUS"
	Alpha3AUT = "AUT"
	Alpha3AZE = "AZE"
	Alpha3BHS = "BHS"
	Alpha3BHR = "BHR"
	Alpha3BGD = "BGD"
	Alpha3BRB = "BRB"
	Alpha3BLR = "BLR"
	Alpha3BEL = "BEL"
	Alpha3BLZ = "BLZ"
	Alpha3BEN = "BEN"
	Alpha3BMU = "BMU"
	Alpha3BTN = "BTN"
	Alpha3BOL = "BOL"
	Alpha3BES = "BES"
	Alpha3BIH = "BIH"
	Alpha3BWA = "BWA"
	Alpha3BVT = "BVT"
	Alpha3BRA = "BRA"
	Alpha3IOT = "IOT"
	Alpha3BRN = "BRN"
	Alpha3BGR = "BGR"
	Alpha3BFA = "BFA"
	Alpha3BDI = "BDI"
	Alpha3CPV = "CPV"
	Alpha3KHM = "KHM"
	Alpha3CMR = "CMR"
	Alpha3CAN = "CAN"
	Alpha3CYM = "CYM"
	Alpha3CAF = "CAF"
	Alpha3TCD = "TCD"
	Alpha3CHL = "CHL"
	Alpha3CHN = "CHN"
	Alpha3CXR = "CXR"
	Alpha3CCK = "CCK"
	Alpha3COL = "COL"
	Alpha3COM = "COM"
	Alpha3COG = "COG"
	Alpha3COD = "COD"
	Alpha3COK = "COK"
	Alpha3CRI = "CRI"
	Alpha3CIV = "CIV"
	Alpha3HRV = "HRV"
	Alpha3CUB = "CUB"
	Alpha3CUW = "CUW"
	Alpha3CYP = "CYP"
	Alpha3CZE = "CZE"
	Alpha3DNK = "DNK"
	Alpha3DJI = "DJI"
	Alpha3DMA = "DMA"
	Alpha3DOM = "DOM"
	Alpha3ECU = "ECU"
	Alpha3EGY = "EGY"
	Alpha3SLV = "SLV"
	Alpha3GNQ = "GNQ"
	Alpha3ERI = "ERI"
	Alpha3EST = "EST"
	Alpha3SWZ = "SWZ"
	Alpha3ETH = "ETH"
	Alpha3FLK = "FLK"
	Alpha3FRO = "FRO"
	Alpha3FJI = "FJI"
	Alpha3FIN = "FIN"
	Alpha3FRA = "FRA"
	Alpha3GUF = "GUF"
	Alpha3PYF = "PYF"
	Alpha3ATF = "ATF"
	Alpha3GAB = "GAB"
	Alpha3GMB = "GMB"
	Alpha3GEO = "GEO"
	Alpha3DEU = "DEU"
	Alpha3GHA = "GHA"
	Alpha3GIB = "GIB"
	Alpha3GRC = "GRC"
	Alpha3GRL = "GRL"
	Alpha3GRD = "GRD"
	Alpha3GLP = "GLP"
	Alpha3GUM = "GUM"
	Alpha3GTM = "GTM"
	Alpha3GGY = "GGY"
	Alpha3GIN = "GIN"
	Alpha3GNB = "GNB"
	Alpha3GUY = "GUY"
	Alpha3HTI = "HTI"
	Alpha3HMD = "HMD"
	Alpha3VAT = "VAT"
	Alpha3HND = "HND"
	Alpha3HKG = "HKG"
	Alpha3HUN = "HUN"
	Alpha3ISL = "ISL"
	Alpha3IND = "IND"
	Alpha3IDN = "IDN"
	Alpha3IRN = "IRN"
	Alpha3IRQ = "IRQ"
	Alpha3IRL = "IRL"
	Alpha3IMN = "IMN"
	Alpha3ISR = "ISR"
	Alpha3ITA = "ITA"
	Alpha3JAM = "JAM"
	Alpha3JPN = "JPN"
	Alpha3JEY = "JEY"
	Alpha3JOR = "JOR"
	Alpha3KAZ = "KAZ"
	Alpha3KEN = "KEN"
	Alpha3KIR = "KIR"
	Alpha3PRK = "PRK"
	Alpha3KOR = "KOR"
	Alpha3KWT = "KWT"
	Alpha3KGZ = "KGZ"
	Alpha3LAO = "LAO"
	Alpha3LVA = "LVA"
	Alpha3LBN = "LBN"
	Alpha3LSO = "LSO"
	Alpha3LBR = "LBR"
	Alpha3LBY = "LBY"
	Alpha3LIE = "LIE"
	Alpha3LTU = "LTU"
	Alpha3LUX = "LUX"
	Alpha3MAC = "MAC"
	Alpha3MDG = "MDG"
	Alpha3MWI = "MWI"
	Alpha3MYS = "MYS"
	Alpha3MDV = "MDV"
	Alpha3MLI = "MLI"
	Alpha3MLT = "MLT"
	Alpha3MHL = "MHL"
	Alpha3MTQ = "MTQ"
	Alpha3MRT = "MRT"
	Alpha3MUS = "MUS"
	Alpha3MYT = "MYT"
	Alpha3MEX = "MEX"
	Alpha3FSM = "FSM"
	Alpha3MDA = "MDA"
	Alpha3MCO = "MCO"
	Alpha3MNG = "MNG"
	Alpha3MNE = "MNE"
	Alpha3MSR = "MSR"
	Alpha3MAR = "MAR"
	Alpha3MOZ = "MOZ"
	Alpha3MMR = "MMR"
	Alpha3NAM = "NAM"
	Alpha3NRU = "NRU"
	Alpha3NPL = "NPL"
	Alpha3NLD = "NLD"
	Alpha3NCL = "NCL"
	Alpha3NZL = "NZL"
	Alpha3NIC = "NIC"
	Alpha3NER = "NER"
	Alpha3NGA = "NGA"
	Alpha3NIU = "NIU"
	Alpha3NFK = "NFK"
	Alpha3MKD = "MKD"
	Alpha3MNP = "MNP"
	Alpha3NOR = "NOR"
	Alpha3OMN = "OMN"
	Alpha3PAK = "PAK"
	Alpha3PLW = "PLW"
	Alpha3PSE = "PSE"
	Alpha3PAN = "PAN"
	Alpha3PNG = "PNG"
	Alpha3PRY = "PRY"
	Alpha3PER = "PER"
	Alpha3PHL = "PHL"
	Alpha3PCN = "PCN"
	Alpha3POL = "POL"
	Alpha3PRT = "PRT"
	Alpha3PRI = "PRI"
	Alpha3QAT = "QAT"
	Alpha3REU = "REU"
	Alpha3ROU = "ROU"
	Alpha3RUS = "RUS"
	Alpha3RWA = "RWA"
	Alpha3BLM = "BLM"
	Alpha3SHN = "SHN"
	Alpha3KNA = "KNA"
	Alpha3LCA = "LCA"
	Alpha3MAF = "MAF"
	Alpha3SPM = "SPM"
	Alpha3VCT = "VCT"
	Alpha3WSM = "WSM"
	Alpha3SMR = "SMR"
	Alpha3STP = "STP"
	Alpha3SAU = "SAU"
	Alpha3SEN = "SEN"
	Alpha3SRB = "SRB"
	Alpha3SYC = "SYC"
	Alpha3SLE = "SLE"
	Alpha3SGP = "SGP"
	Alpha3SXM = "SXM"
	Alpha3SVK = "SVK"
	Alpha3SVN = "SVN"
	Alpha3SLB = "SLB"
	Alpha3SOM = "SOM"
	Alpha3ZAF = "ZAF"
	Alpha3SGS = "SGS"
	Alpha3SSD = "SSD"
	Alpha3ESP = "ESP"
	Alpha3LKA = "LKA"
	Alpha3SDN = "SDN"
	Alpha3SUR = "SUR"
	Alpha3SJM = "SJM"
	Alpha3SWE = "SWE"
	Alpha3CHE = "CHE"
	Alpha3SYR = "SYR"
	Alpha3TWN = "TWN"
	Alpha3TJK = "TJK"
	Alpha3TZA = "TZA"
	Alpha3THA = "THA"
	Alpha3TLS = "TLS"
	Alpha3TGO = "TGO"
	Alpha3TKL = "TKL"
	Alpha3TON = "TON"
	Alpha3TTO = "TTO"
	Alpha3TUN = "TUN"
	Alpha3TUR = "TUR"
	Alpha3TKM = "TKM"
	Alpha3TCA = "TCA"
	Alpha3TUV = "TUV"
	Alpha3UGA = "UGA"
	Alpha3UKR = "UKR"
	Alpha3ARE = "ARE"
	Alpha3GBR = "GBR"
	Alpha3USA = "USA"
	Alpha3UMI = "UMI"
	Alpha3URY = "URY"
	Alpha3UZB = "UZB"
	Alpha3VUT = "VUT"
	Alpha3VEN = "VEN"
	Alpha3VNM = "VNM"
	Alpha3VGB = "VGB"
	Alpha3VIR = "VIR"
	Alpha3WLF = "WLF"
	Alpha3ESH = "ESH"
	Alpha3YEM = "YEM"
	Alpha3ZMB = "ZMB"
	Alpha3ZWE = "ZWE"
)

Predefined ISO 3166-1 alpha-3 codes.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Country ¶

type Country struct {
	Alpha2                 string `json:"alpha-2"`                  // ISO 3166-1 alpha-2 code
	Alpha3                 string `json:"alpha-3"`                  // ISO 3166-1 alpha-3 code
	Capital                string `json:"capital"`                  // Capital city of the country
	ContinentName          string `json:"continent_name"`           // The Name of the continent the country is located in
	CountryCode            string `json:"country-code"`             // Numeric ISO 3166-1 code
	CurrencyCode           string `json:"currency_code"`            // ISO 4217 currency code
	ISO31662               string `json:"iso_3166-2"`               // ISO 3166-2 code for subdivisions
	IntermediateRegion     string `json:"intermediate-region"`      // Name of the intermediate region (if applicable)
	IntermediateRegionCode string `json:"intermediate-region-code"` // Code for the intermediate region (if applicable)
	Name                   string `json:"name"`                     // Name of the country
	Region                 string `json:"region"`                   // Name of the region the country is located in
	RegionCode             string `json:"region-code"`              // Code for the region (e.g., continent code)
	SubRegion              string `json:"sub-region"`               // The Name of the subregion the country is located in
	SubRegionCode          string `json:"sub-region-code"`          // Code for the sub-region (e.g., continent sub-region code)
}

Country is the single country in the list of countries (ISO-3166)

func GetByAlpha2 ¶

func GetByAlpha2(alpha2 string) *Country

GetByAlpha2 retrieves a Country by its alpha-2 code in a case-insensitive search.

This function performs the following steps: - Normalizes the provided code to uppercase - Performs a constant-time map lookup using the normalized code

- Returns the Country pointer on success - Returns nil if no match is located

Parameters: - alpha2: two-letter ISO 3166 code used for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a map for constant-time retrieval - Returned pointer references package-level data without copying

Example ¶

ExampleGetByAlpha2 is an example of GetByAlpha2()

country := GetByAlpha2(testCountryAlpha2)
fmt.Printf(
	"country: %s alpha2: %s alpha3: %s code: %s",
	country.Name, country.Alpha2, country.Alpha3, country.CountryCode,
)

Output:

country: United States of America alpha2: US alpha3: USA code: 840

func GetByAlpha3 ¶

func GetByAlpha3(alpha3 string) *Country

GetByAlpha3 retrieves a Country using its alpha-3 code in a case-insensitive search.

This function performs the following steps: - Converts the incoming code to uppercase - Performs a constant-time map lookup using the uppercase code

- Returns the Country pointer if found - Returns nil when the code is not present

Parameters: - alpha3: three-letter ISO 3166 code used for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a map for constant-time retrieval - Returned pointer references global data and should not be mutated

Example ¶

ExampleGetByAlpha3 is an example of GetByAlpha3()

country := GetByAlpha3(testCountryAlpha3)
fmt.Printf(
	"country: %s alpha2: %s alpha3: %s code: %s",
	country.Name, country.Alpha2, country.Alpha3, country.CountryCode,
)

Output:

country: United States of America alpha2: US alpha3: USA code: 840

func GetByCapital ¶ added in v1.0.1

func GetByCapital(capital string) *Country

GetByCapital retrieves a Country by its capital city in a case-insensitive search.

This function performs the following steps: - Converts the provided capital name to lowercase - Performs a constant-time map lookup using the normalized name

- Returns the Country pointer when a match exists - Returns nil if the capital is not found

Parameters: - capital: the capital city used for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a prebuilt map for constant-time retrieval - Returned pointer references package data directly

Example ¶

ExampleGetByCapital is an example of GetByCapital()

country := GetByCapital(testCountryCapital)
fmt.Printf(
	"country: %s capital: %s",
	country.Name, country.Capital,
)

Output:

country: United States of America capital: Washington

func GetByCountryCode ¶

func GetByCountryCode(code string) *Country

GetByCountryCode looks up a Country by its numeric code using a case-sensitive comparison.

This function performs the following steps: - Performs a constant-time map lookup using the numeric code

- Returns the Country pointer when a match is found - Returns nil if the code does not exist in the list

Parameters: - code: numeric ISO 3166 code provided for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a map for constant-time retrieval - The returned Country pointer references package data directly

Example ¶

ExampleGetByCountryCode is an example of GetByCountryCode()

country := GetByCountryCode(testCountryCode)
fmt.Printf(
	"country: %s alpha2: %s alpha3: %s code: %s",
	country.Name, country.Alpha2, country.Alpha3, country.CountryCode,
)

Output:

country: United States of America alpha2: US alpha3: USA code: 840

func GetByISO31662 ¶

func GetByISO31662(iso string) *Country

GetByISO31662 locates a Country by its ISO 3166-2 code using a case-insensitive match.

This function performs the following steps: - Converts the provided code to uppercase for uniform comparison - Performs a constant-time map lookup using the normalized code

- Returns the Country pointer when a match exists - Returns nil if no matching code is found

Parameters: - iso: the ISO 3166-2 code used for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a map for constant-time retrieval - Returned pointer references global data and should be treated as read-only

Example ¶

ExampleGetByISO31662 is an example of GetByISO31662()

country := GetByISO31662(testCountryISO)
fmt.Printf(
	"country: %s alpha2: %s alpha3: %s code: %s",
	country.Name, country.Alpha2, country.Alpha3, country.CountryCode,
)

Output:

country: United States of America alpha2: US alpha3: USA code: 840

func GetByName ¶

func GetByName(name string) *Country

GetByName retrieves a Country by its name in a case-insensitive search.

This function performs the following steps: - Converts the input name to lowercase for normalization - Performs a constant-time map lookup using the normalized name

- Returns the matching Country pointer when found - Returns nil if no matching country exists

Parameters: - name: country name used for the lookup

Returns: - Pointer to the Country struct, or nil when no match is found

Side Effects: - None

Notes: - Lookup uses a prebuilt map for constant-time access - The result references the internal Country struct without copying

Example ¶

ExampleGetByName is an example of GetByName()

country := GetByName(testCountry)
fmt.Printf(
	"country: %s alpha2: %s alpha3: %s code: %s",
	country.Name, country.Alpha2, country.Alpha3, country.CountryCode,
)

Output:

country: United States of America alpha2: US alpha3: USA code: 840

Example (ShowAll) ¶

ExampleGetByName_ShowAll

country := GetByName(testCountry)
fmt.Printf("%+v\n", country)

Output:

&{Alpha2:US Alpha3:USA Capital:Washington ContinentName:North America CountryCode:840 CurrencyCode:USD ISO31662:ISO 3166-2:US IntermediateRegion: IntermediateRegionCode: Name:United States of America Region:Americas RegionCode:019 SubRegion:Northern America SubRegionCode:021}

type CountryList ¶

type CountryList []*Country

CountryList is a list of country structs

func GetAll ¶

func GetAll() CountryList

GetAll provides a copy of every Country currently loaded.

This function performs the following steps: - Creates a new slice with the same length as the internal country slice - Appends all existing Country pointers into that slice - Returns the new slice to the caller

Parameters: - None

Returns: - CountryList containing pointers to all Country structs

Side Effects: - None

Notes: - The Country pointers reference global data but the returned slice is a copy - Modifying the slice does not alter the package-level slice

Example ¶

ExampleGetAll is an example of GetAll()

all := GetAll()
fmt.Printf("countries found: %d", len(all))

Output:

countries found: 249

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
data Package data contains the data for the currencies	Package data contains the data for the currencies
examples Package main provides examples of how to use the go-countries package.	Package main provides examples of how to use the go-countries package.
generate This program generates the structs from JSON	This program generates the structs from JSON

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL