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
Redistributable license
Tagged version
Stable version
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 ¶