countries

package module

v0.2.0 Latest Latest Go to latest Published: Oct 6, 2023 License: MIT Imports: 2 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/pioz/countries

Links

Open Source Insights

README ¶

Countries

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

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 ¶

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"`
	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 (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.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
🇺🇸

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
generator

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

README ¶

Countries

Installation

Usage

Identification Codes

Names & Translations

Subdivisions

Locations

Boundary Boxes

Telephone Routing (E164)

Timezones

Formatted Addresses

VAT Rates

European Union Membership

European Economic Area Membership

European Single Market Membership

Country Finders

Contributing

License

Documentation ¶

Index ¶

Examples ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type Bounds ¶

type Coord ¶

type Country ¶

func Get ¶

func InEU ¶

func InRegion ¶

func InSubregion ¶

func (*Country) EmojiFlag ¶

func (*Country) FormatAddress ¶

func (*Country) GDPRCompliant ¶ added in v0.2.0

func (*Country) HasPostalCode ¶

func (*Country) MatchPostalCode ¶

func (*Country) Subdivision ¶

func (*Country) SubdivisionByName ¶

type Geo ¶

type Subdivision ¶

type VatRates ¶

Source Files ¶

Directories ¶