countries

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 4, 2025 License: MIT Imports: 2 Imported by: 0

README

Countries

Go Go Report Card codecov awesome-go GoReference

Countries is a port of Ruby Countries for Go.

  • Standard ISO3166-1 (countries)
  • Standard ISO3166-2 (states/subdivisions)
  • Standard ISO4217 (currencies)
  • Standard E.164 (phone numbers)
  • Country Name Translations
  • VAT Rates
  • Address Formats
  • Timezones

Installation

go get github.com/pioz/countries

Usage

Identification Codes
c := countries.Get("US")
fmt.Println(c.Number)
fmt.Println(c.Alpha2)
fmt.Println(c.Alpha3)
fmt.Println(c.GEC)
// Output:
// 840
// US
// USA
// US
Names & Translations
c := countries.Get("US")
fmt.Println(c.ISOLongName)
fmt.Println(c.ISOShortName)
fmt.Println(c.UnofficialNames)
fmt.Println(c.Translations["en"])
fmt.Println(c.Translations["it"])
fmt.Println(c.Translations["de"])
fmt.Println(c.Nationality)
fmt.Println(c.Capital)
fmt.Println(c.EmojiFlag())
// Output:
// The United States of America
// United States of America
// [United States USA Vereinigte Staaten von Amerika États-Unis Estados Unidos アメリカ合衆国 Verenigde Staten Соединенные Штаты Америки]
// United States
// Stati Uniti
// Vereinigte Staaten
// American
// Washington
// 🇺🇸
Subdivisions
c := countries.Get("US")
ca := c.Subdivision("CA")
tx := c.SubdivisionByName("Texas")
fmt.Println(len(c.Subdivisions))
fmt.Println(ca.Name)
fmt.Println(ca.Type)
fmt.Println(ca.Translations["de"])
fmt.Println(ca.Geo.Latitude)
fmt.Println(tx.Code)
// Output:
// 57
// California
// state
// Kalifornien
// 36.778261
// TX
Locations
c := countries.Get("US")
fmt.Println(c.Geo.Latitude)
fmt.Println(c.Geo.Longitude)
fmt.Println(c.Region)
fmt.Println(c.Subregion)
fmt.Println(c.Continent)
fmt.Println(c.WorldRegion)
// Output:
// 37.09024
// -95.712891
// Americas
// Northern America
// North America
// AMER
Boundary Boxes
c := countries.Get("US")
fmt.Println(c.Geo.MinLatitude)
fmt.Println(c.Geo.MaxLatitude)
fmt.Println(c.Geo.MinLongitude)
fmt.Println(c.Geo.MaxLongitude)
fmt.Println(c.Geo.Bounds.Northeast.Lat)
fmt.Println(c.Geo.Bounds.Northeast.Lng)
fmt.Println(c.Geo.Bounds.Southwest.Lat)
fmt.Println(c.Geo.Bounds.Southwest.Lng)
// Output:
// 18.91619
// 71.3577635769
// -171.791110603
// -66.96466
// 71.3577635769
// -66.96466
// 18.91619
// -171.791110603
Telephone Routing (E164)
c := countries.Get("US")
fmt.Println(c.CountryCode)
fmt.Println(c.NationalDestinationCodeLengths)
fmt.Println(c.NationalNumberLengths)
fmt.Println(c.InternationalPrefix)
fmt.Println(c.NationalPrefix)
// Output:
// 1
// [3]
// [10]
// 011
// 1
Timezones
c := countries.Get("DE")
fmt.Println(c.Timezones)
// Output: [Europe/Berlin Europe/Busingen]
Formatted Addresses
c := countries.Get("US")
fmt.Println(c.AddressFormat)
fmt.Println("---")
fmt.Println(c.FormatAddress("John Smith", "1084 Nuzum Court", "14214", "Buffalo", "New York"))
// Output:
// {{recipient}}
// {{street}}
// {{city}} {{region_short}} {{postalcode}}
// {{country}}
// ---
// John Smith
// 1084 Nuzum Court
// Buffalo NY 14214
// United States of America
VAT Rates
c := countries.Get("IE")
fmt.Println(c.VatRates.Standard)
fmt.Println(c.VatRates.Reduced)
fmt.Println(c.VatRates.SuperReduced)
fmt.Println(c.VatRates.Parking)
// Output:
// 23
// [9 13]
// 4
// 13
European Union Membership
c := countries.Get("IT")
fmt.Println(c.EUMember)
// Output: true
European Economic Area Membership
c := countries.Get("FR")
fmt.Println(c.EEAMember)
// Output: true
European Single Market Membership
c := countries.Get("CH")
fmt.Println(c.ESMMember)
// Output: true
GDPR Compliant
c := countries.Get("IT")
fmt.Println(c.GDPRCompliant())
// Output: true
Country Finders
allCountries := countries.All
countriesInEurope := countries.InRegion("Europe")
countriesInSouthernAsia := countries.InSubregion("Southern Asia")
countriesInEU := countries.InEU()
fmt.Println(len(allCountries))
fmt.Println(len(countriesInEurope))
fmt.Println(len(countriesInSouthernAsia))
fmt.Println(len(countriesInEU))
// Output:
// 249
// 51
// 9
// 27

Please refer to the godoc for all country fields, available functions and more. Furthermore, tests are a good and helpful starting point.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/pioz/countries/issues.

License

The package is available as open source under the terms of the MIT License.

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var All = []Country{}/* 249 elements not displayed */

All is a slice with all countries ordered by alpha2 code.

View Source 
var Alpha2 = []string{} /* 249 elements not displayed */

Alpha2 is a slice with all country alpha2 codes.

View Source 
var Regions = []string{"Africa", "Americas", "Asia", "Europe", "Oceania"}

Regions is a slice with all region names.

View Source 
var Subregions = []string{"Australia and New Zealand", "Caribbean", "Central America", "Central Asia", "Eastern Africa", "Eastern Asia", "Eastern Europe", "Melanesia", "Micronesia", "Middle Africa", "Northern Africa", "Northern America", "Northern Europe", "Polynesia", "South America", "South-Eastern Asia", "Southern Africa", "Southern Asia", "Southern Europe", "Western Africa", "Western Asia", "Western Europe"}

Subregions is a slice with all subregion names.

Functions

This section is empty.

Types

type Bounds 

type Bounds struct {
	Northeast Coord `yaml:"northeast"`
	Southwest Coord `yaml:"southwest"`
}

Bounds represents a country bounds: the northeast and the southwest geographic coordinates.

type Coord 

type Coord struct {
	Lat float64 `yaml:"lat"`
	Lng float64 `yaml:"lng"`
}

Coord represents a geographic coordinate.

type Country 

type Country struct {
	AddressFormat                  string                 `yaml:"address_format"`
	Alpha2                         string                 `yaml:"alpha2"`
	Alpha3                         string                 `yaml:"alpha3"`
	Capital                        string                 `yaml:"capital"`
	Continent                      string                 `yaml:"continent"`
	CountryCode                    string                 `yaml:"country_code"`
	CurrencyCode                   string                 `yaml:"currency_code"`
	EEAMember                      bool                   `yaml:"eea_member"`
	EUMember                       bool                   `yaml:"eu_member"`
	G7Member                       bool                   `yaml:"g7_member"`
	G20Member                      bool                   `yaml:"g20_member"`
	ESMMember                      bool                   `yaml:"esm_member"`
	GEC                            string                 `yaml:"gec"`
	Geo                            Geo                    `yaml:"geo"`
	InternationalPrefix            string                 `yaml:"international_prefix"`
	IOC                            string                 `yaml:"ioc"`
	ISOLongName                    string                 `yaml:"iso_long_name"`
	ISOShortName                   string                 `yaml:"iso_short_name"`
	ISOShortNameLowerCase          string                 `yaml:"iso_short_name_lower_case"`
	LanguagesOfficial              []string               `yaml:"languages_official"`
	LanguagesSpoken                []string               `yaml:"languages_spoken"`
	NationalDestinationCodeLengths []int                  `yaml:"national_destination_code_lengths"`
	NationalNumberLengths          []int                  `yaml:"national_number_lengths"`
	NationalPrefix                 string                 `yaml:"national_prefix"`
	Nationality                    string                 `yaml:"nationality"`
	Number                         string                 `yaml:"number"`
	PostalCodeFormat               string                 `yaml:"postal_code_format"`
	Region                         string                 `yaml:"region"`
	StartOfWeek                    string                 `yaml:"start_of_week"`
	Subdivisions                   map[string]Subdivision `yaml:"-"`
	Subregion                      string                 `yaml:"subregion"`
	Timezones                      []string               `yaml:"-"`
	Translations                   map[string]string      `yaml:"-"`
	UnLocode                       string                 `yaml:"un_locode"`
	UnofficialNames                []string               `yaml:"unofficial_names"`
	VatRates                       VatRates               `yaml:"vat_rates"`
	WorldRegion                    string                 `yaml:"world_region"`
}

Country store all information about a country.

func Get 

func Get(alpha2 string) *Country

Get returns the country identified by alpha2 code.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.ISOShortName)
}

Output:

United States of America
Example (ReadmeBoundaryBoxes) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.Geo.MinLatitude)
	fmt.Println(c.Geo.MaxLatitude)
	fmt.Println(c.Geo.MinLongitude)
	fmt.Println(c.Geo.MaxLongitude)
	fmt.Println(c.Geo.Bounds.Northeast.Lat)
	fmt.Println(c.Geo.Bounds.Northeast.Lng)
	fmt.Println(c.Geo.Bounds.Southwest.Lat)
	fmt.Println(c.Geo.Bounds.Southwest.Lng)
}

Output:

18.91619
71.3577635769
-171.791110603
-66.96466
71.3577635769
-66.96466
18.91619
-171.791110603
Example (ReadmeCountryFinders) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	allCountries := countries.All
	countriesInEurope := countries.InRegion("Europe")
	countriesInSouthernAsia := countries.InSubregion("Southern Asia")
	countriesInEU := countries.InEU()
	fmt.Println(len(allCountries))
	fmt.Println(len(countriesInEurope))
	fmt.Println(len(countriesInSouthernAsia))
	fmt.Println(len(countriesInEU))
}

Output:

249
51
9
34
Example (ReadmeEuropeanEconomicAreaMembership) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("FR")
	fmt.Println(c.EEAMember)
}

Output:

true
Example (ReadmeEuropeanSingleMarketMembership) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("CH")
	fmt.Println(c.ESMMember)
}

Output:

true
Example (ReadmeEuropeanUnionMembership) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("IT")
	fmt.Println(c.EUMember)
}

Output:

true
Example (ReadmeFormattedAddresses) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.AddressFormat)
	fmt.Println("---")
	fmt.Println(c.FormatAddress("John Smith", "1084 Nuzum Court", "14214", "Buffalo", "New York"))
}

Output:

{{recipient}}
{{street}}
{{city}} {{region_short}} {{postalcode}}
{{country}}
---
John Smith
1084 Nuzum Court
Buffalo NY 14214
United States of America
Example (ReadmeGDPRCompliant) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("IT")
	fmt.Println(c.GDPRCompliant())
}

Output:

true
Example (ReadmeIdentificationCodes) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.Number)
	fmt.Println(c.Alpha2)
	fmt.Println(c.Alpha3)
	fmt.Println(c.GEC)
}

Output:

840
US
USA
US
Example (ReadmeLocations) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.Geo.Latitude)
	fmt.Println(c.Geo.Longitude)
	fmt.Println(c.Region)
	fmt.Println(c.Subregion)
	fmt.Println(c.Continent)
	fmt.Println(c.WorldRegion)
}

Output:

37.09024
-95.712891
Americas
Northern America
North America
AMER
Example (ReadmeNamesAndTranslations) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.ISOLongName)
	fmt.Println(c.ISOShortName)
	fmt.Println(c.ISOShortNameLowerCase)
	fmt.Println(c.UnofficialNames)
	fmt.Println(c.Translations["en"])
	fmt.Println(c.Translations["it"])
	fmt.Println(c.Translations["de"])
	fmt.Println(c.Nationality)
	fmt.Println(c.Capital)
	fmt.Println(c.EmojiFlag())
}

Output:

The United States of America
United States of America
United States of America (the)
[United States United States of America USA Vereinigte Staaten von Amerika États-Unis Estados Unidos アメリカ合衆国 Verenigde Staten Соединенные Штаты Америки]
United States
Stati Uniti
Vereinigte Staaten
American
Washington
🇺🇸
Example (ReadmeSubdivisions) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	ca := c.Subdivision("CA")
	tx := c.SubdivisionByName("Texas")
	fmt.Println(len(c.Subdivisions))
	fmt.Println(ca.Name)
	fmt.Println(ca.Type)
	fmt.Println(ca.Translations["de"])
	fmt.Println(ca.Geo.Latitude)
	fmt.Println(tx.Code)
}

Output:

57
California
state
Kalifornien
36.778261
TX
Example (ReadmeTelephoneRouting) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.CountryCode)
	fmt.Println(c.NationalDestinationCodeLengths)
	fmt.Println(c.NationalNumberLengths)
	fmt.Println(c.InternationalPrefix)
	fmt.Println(c.NationalPrefix)
}

Output:

1
[3]
[10]
011
1
Example (ReadmeTimezones) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("DE")
	fmt.Println(c.Timezones)
}

Output:

[Europe/Berlin Europe/Busingen]
Example (ReadmeVATRates) 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("IE")
	fmt.Println(c.VatRates.Standard)
	fmt.Println(c.VatRates.Reduced)
	fmt.Println(c.VatRates.SuperReduced)
	fmt.Println(c.VatRates.Parking)
}

Output:

23
[9 13]
4
13

func InEU 

func InEU() []Country

InEU returns all countries that are members of the European Union.

func InRegion 

func InRegion(region string) []Country

InRegion returns all countries that are part of the region.

func InSubregion 

func InSubregion(subregion string) []Country

InSubregion returns all countries that are part of the subregion.

func (*Country) EmojiFlag 

func (c *Country) EmojiFlag() string

EmojiFlag returns the country Emoji flag.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.EmojiFlag())
}

Output:

🇺🇸

func (*Country) FormatAddress 

func (c *Country) FormatAddress(recipient, street, postalCode, city, region string) string

FormatAddress returns the formatted address based on country.AddressFormat template.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	fmt.Println(c.FormatAddress("John Smith", "1084 Nuzum Court", "14214", "Buffalo", "New York"))
}

Output:

John Smith
1084 Nuzum Court
Buffalo NY 14214
United States of America

func (*Country) GDPRCompliant added in v0.2.0 

func (c *Country) GDPRCompliant() bool

GDPRCompliant returns true if the country is GDPR (General Data Protection Regulation) compliant. A country is GDPR compliant if is a member of the European Economic Area or it is UK.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("IT")
	fmt.Println(c.GDPRCompliant())
}

Output:

true

func (*Country) HasPostalCode 

func (c *Country) HasPostalCode() bool

HasPostalCode determines whether the country has postal codes. It returns true if the country has postal codes, and false if it does not.

func (*Country) MatchPostalCode 

func (c *Country) MatchPostalCode(postalCode string) bool

MatchPostalCode returns true if postalCode has a valid format for the country. If the country does not have a postal code, returns false.

func (*Country) Subdivision 

func (c *Country) Subdivision(code string) Subdivision

Subdivision returns the country's subdivision identified by code. If the code is not valid or not found returns a zero value Subdivision.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	ca := c.Subdivision("CA")
	fmt.Println(ca.Name)
}

Output:

California

func (*Country) SubdivisionByName 

func (c *Country) SubdivisionByName(name string) Subdivision

SubdivisionByName returns the country's subdivision with name name. If the name is not valid or not found returns a zero value Subdivision.

Example 
package main

import (
	"fmt"

	"github.com/pioz/countries"
)

func main() {
	c := countries.Get("US")
	ca := c.SubdivisionByName("Texas")
	fmt.Println(ca.Code)
}

Output:

TX

type Geo 

type Geo struct {
	Latitude     float64 `yaml:"latitude"`
	Longitude    float64 `yaml:"longitude"`
	MaxLatitude  float64 `yaml:"max_latitude"`
	MaxLongitude float64 `yaml:"max_longitude"`
	MinLatitude  float64 `yaml:"min_latitude"`
	MinLongitude float64 `yaml:"min_longitude"`
	Bounds       Bounds  `yaml:"bounds"`
}

Bounds store geographic informations of a country.

type Subdivision 

type Subdivision struct {
	Name         string            `yaml:"name"`
	Code         string            `yaml:"code"`
	Type         string            `yaml:"type"`
	Capital      bool              `yaml:"capital"`
	Geo          Geo               `yaml:"geo"`
	Translations map[string]string `yaml:"translations"`
}

Subdivision store information about a subdivision like a region or a province or a state or a metropolitan city of a country.

type VatRates 

type VatRates struct {
	Standard     int   `yaml:"standard"`
	Reduced      []int `yaml:"reduced"`
	SuperReduced int   `yaml:"super_reduced"`
	Parking      int   `yaml:"parking"`
}

VatRates store the VAT (Value Added Tax) rates of a country.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.