countrycode

Documentation

Overview

Package countrycode provides information about countries and their ISO-3166 Codes. The default data originates from multiple sources, including ISO-3166, CIA, United Nations, and Wikipedia. The data is stored in a compact binary format for fast access and small memory footprint. It is also possible to load custom country data.

Index

• type CountryData
• type Data
  • func New(cdata []*CountryData) (*Data, error)
  • func (d *Data) CountriesByIntermediateRegionCode(code string) ([]*CountryData, error)
  • func (d *Data) CountriesByIntermediateRegionName(name string) ([]*CountryData, error)
  • func (d *Data) CountriesByRegionCode(code string) ([]*CountryData, error)
  • func (d *Data) CountriesByRegionName(name string) ([]*CountryData, error)
  • func (d *Data) CountriesByStatusID(id uint8) ([]*CountryData, error)
  • func (d *Data) CountriesByStatusName(name string) ([]*CountryData, error)
  • func (d *Data) CountriesBySubRegionCode(code string) ([]*CountryData, error)
  • func (d *Data) CountriesBySubRegionName(name string) ([]*CountryData, error)
  • func (d *Data) CountriesByTLD(tld string) ([]*CountryData, error)
  • func (d *Data) CountryByAlpha2Code(alpha2 string) (*CountryData, error)
  • func (d *Data) CountryByAlpha3Code(alpha3 string) (*CountryData, error)
  • func (d *Data) CountryByNumericCode(num string) (*CountryData, error)
  • func (d *Data) EnumIntermediateRegion() map[string]string
  • func (d *Data) EnumRegion() map[string]string
  • func (d *Data) EnumStatus() map[string]string
  • func (d *Data) EnumSubRegion() map[string]string
• type Names

Examples

• Data.CountryByAlpha2Code
• Data.CountryByAlpha2Code (Export)
• Data.CountryByAlpha3Code
• Data.CountryByNumericCode

Types

type CountryData

type CountryData struct {
	StatusCode             uint8  `json:"statusCode"`
	Status                 string `json:"status"`
	Alpha2Code             string `json:"alpha2Code"`
	Alpha3Code             string `json:"alpha3Code"`
	NumericCode            string `json:"numericCode"`
	NameEnglish            string `json:"nameEnglish"`
	NameFrench             string `json:"nameFrench"`
	Region                 string `json:"region"`
	SubRegion              string `json:"subRegion"`
	IntermediateRegion     string `json:"intermediateRegion"`
	RegionCode             string `json:"regionCode"`
	SubRegionCode          string `json:"subRegionCode"`
	IntermediateRegionCode string `json:"intermediateRegionCode"`
	TLD                    string `json:"tld"`
}

CountryData contains the country data to be returned.

type Data

type Data struct {
	// contains filtered or unexported fields
}

Data contains the internal country Data and various indexes.

func New

func New(cdata []*CountryData) (*Data, error)

New generates the country data, including various indexes. If the cdata parameter is nil, the embedded default data is used. The generated object should be reused to avoid copying the data.

Default data sources (updated at: 2024-07-17):

• https://www.iso.org/iso-3166-country-codes.html
• https://www.cia.gov/the-world-factbook/references/country-data-codes/
• https://unstats.un.org/unsd/methodology/m49/overview/
• https://en.wikipedia.org/wiki/ISO_3166
• https://en.wikipedia.org/wiki/ISO_3166-1
• https://en.wikipedia.org/wiki/ISO_3166-2
• https://en.wikipedia.org/wiki/ISO_3166-3
• https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
• https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
• https://en.wikipedia.org/wiki/ISO_3166-1_numeric

func (*Data) CountriesByIntermediateRegionCode

func (d *Data) CountriesByIntermediateRegionCode(code string) ([]*CountryData, error)

CountriesByIntermediateRegionCode returns a list of countries in the given intermediate region code (e.g. "014" for Eastern Africa). See EnumIntermediateRegion() for a list of valid intermediate region codes.

func (*Data) CountriesByIntermediateRegionName

func (d *Data) CountriesByIntermediateRegionName(name string) ([]*CountryData, error)

CountriesByIntermediateRegionName returns a list of countries in the given intermediate region name (e.g. "Eastern Africa"). See EnumIntermediateRegion() for a list of valid intermediate region names.

func (*Data) CountriesByRegionCode

func (d *Data) CountriesByRegionCode(code string) ([]*CountryData, error)

CountriesByRegionCode returns a list of countries in the given region code (e.g. "150" for Europe). See EnumRegion() for a list of valid region codes.

func (*Data) CountriesByRegionName

func (d *Data) CountriesByRegionName(name string) ([]*CountryData, error)

CountriesByRegionName returns a list of countries in the given region name (e.g. "Europe"). See EnumRegion() for a list of valid region names.

func (*Data) CountriesByStatusID

func (d *Data) CountriesByStatusID(id uint8) ([]*CountryData, error)

CountriesByStatusID returns a list of countries with the given status ID (0-6). See EnumStatus() for a list of valid status IDs.

func (*Data) CountriesByStatusName

func (d *Data) CountriesByStatusName(name string) ([]*CountryData, error)

CountriesByStatusName returns a list of countries with the given status name (e.g. "Officially assigned"). See EnumStatus() for a list of valid status names.

func (*Data) CountriesBySubRegionCode

func (d *Data) CountriesBySubRegionCode(code string) ([]*CountryData, error)

CountriesBySubRegionCode returns a list of countries in the given sub-region code (e.g. "039" for Southern Europe). See EnumSubRegion() for a list of valid sub-region codes.

func (*Data) CountriesBySubRegionName

func (d *Data) CountriesBySubRegionName(name string) ([]*CountryData, error)

CountriesBySubRegionName returns a list of countries in the given sub-region name (e.g. "Southern Europe"). See EnumSubRegion() for a list of valid sub-region names.

func (*Data) CountriesByTLD

func (d *Data) CountriesByTLD(tld string) ([]*CountryData, error)

CountriesByTLD returns a list of countries with the given TLD (top-level domain) code (e.g. "it" for Italy).

func (*Data) CountryByAlpha2Code

func (d *Data) CountryByAlpha2Code(alpha2 string) (*CountryData, error)

CountryByAlpha2Code returns the country data for the given ISO-3166 Alpha-2 code (e.g. "IT" for Italy).

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/Vonage/gosrvlib/pkg/countrycode"
)

func main() {
	data, err := countrycode.New(nil)
	if err != nil {
		log.Fatal(err)
	}

	got, err := data.CountryByAlpha2Code("ZW")
	if err != nil {
		log.Fatal(err)
	}

	b, err := json.MarshalIndent(got, "", "  ")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))

}

Output:

{
  "statusCode": 1,
  "status": "Officially assigned",
  "alpha2Code": "ZW",
  "alpha3Code": "ZWE",
  "numericCode": "716",
  "nameEnglish": "Zimbabwe",
  "nameFrench": "Zimbabwe (le)",
  "region": "Africa",
  "subRegion": "Sub-Saharan Africa",
  "intermediateRegion": "Eastern Africa",
  "regionCode": "002",
  "subRegionCode": "202",
  "intermediateRegionCode": "014",
  "tld": "zw"
}

Example (Export)

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/Vonage/gosrvlib/pkg/countrycode"
)

func main() {
	data, err := countrycode.New(nil)
	if err != nil {
		log.Fatal(err)
	}

	expCountries := make([]*countrycode.CountryData, 0, 26*26)

	// Generate all 2-letter country codes possible combinations, from AA to ZZ.
	for c1 := 'A'; c1 <= 'Z'; c1++ {
		for c0 := 'A'; c0 <= 'Z'; c0++ {
			alpha2 := string([]rune{c1, c0})

			// Decode country data from the 2-letter country code.
			country, err := data.CountryByAlpha2Code(alpha2)
			if err != nil {
				log.Fatal(err)
			}

			expCountries = append(expCountries, country)
		}
	}

	// Export the country data to JSON.
	jsonExpCountries, err := json.MarshalIndent(expCountries, "", "  ")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(jsonExpCountries))
}

func (*Data) CountryByAlpha3Code

func (d *Data) CountryByAlpha3Code(alpha3 string) (*CountryData, error)

CountryByAlpha3Code returns the country data for the given ISO-3166 Alpha-3 code (e.g. "ITA" for Italy).

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/Vonage/gosrvlib/pkg/countrycode"
)

func main() {
	data, err := countrycode.New(nil)
	if err != nil {
		log.Fatal(err)
	}

	got, err := data.CountryByAlpha3Code("ZWE")
	if err != nil {
		log.Fatal(err)
	}

	b, err := json.MarshalIndent(got, "", "  ")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))

}

Output:

{
  "statusCode": 1,
  "status": "Officially assigned",
  "alpha2Code": "ZW",
  "alpha3Code": "ZWE",
  "numericCode": "716",
  "nameEnglish": "Zimbabwe",
  "nameFrench": "Zimbabwe (le)",
  "region": "Africa",
  "subRegion": "Sub-Saharan Africa",
  "intermediateRegion": "Eastern Africa",
  "regionCode": "002",
  "subRegionCode": "202",
  "intermediateRegionCode": "014",
  "tld": "zw"
}

func (*Data) CountryByNumericCode

func (d *Data) CountryByNumericCode(num string) (*CountryData, error)

CountryByNumericCode returns the country data for the given ISO-3166 Numeric code (e.g. "380" for Italy).

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/Vonage/gosrvlib/pkg/countrycode"
)

func main() {
	data, err := countrycode.New(nil)
	if err != nil {
		log.Fatal(err)
	}

	got, err := data.CountryByNumericCode("716")
	if err != nil {
		log.Fatal(err)
	}

	b, err := json.MarshalIndent(got, "", "  ")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))

}

Output:

{
  "statusCode": 1,
  "status": "Officially assigned",
  "alpha2Code": "ZW",
  "alpha3Code": "ZWE",
  "numericCode": "716",
  "nameEnglish": "Zimbabwe",
  "nameFrench": "Zimbabwe (le)",
  "region": "Africa",
  "subRegion": "Sub-Saharan Africa",
  "intermediateRegion": "Eastern Africa",
  "regionCode": "002",
  "subRegionCode": "202",
  "intermediateRegionCode": "014",
  "tld": "zw"
}

func (*Data) EnumIntermediateRegion

func (d *Data) EnumIntermediateRegion() map[string]string

EnumIntermediateRegion returns the intermediate-region codes and names.

func (*Data) EnumRegion

func (d *Data) EnumRegion() map[string]string

EnumRegion returns the region codes and names.

func (*Data) EnumStatus

func (d *Data) EnumStatus() map[string]string

EnumStatus returns the status codes and names.

func (*Data) EnumSubRegion

func (d *Data) EnumSubRegion() map[string]string

EnumSubRegion returns the sub-region codes and names.

type Names

type Names struct {
	EN string
	FR string
}

Names contains the English and French Names of a country.