go-restcountries is a wrapper for the Countrylayer REST Countries API (formerly restcountries.eu), written in Go. The latest (v2) version of the API is used.
Note: the original free REST Countries API provided by restcountries.eu is now the Countrylayer API, hosted at countrylayer.com which requires an API key. Go REST Countries v2 fully supports the Countrylayer API.
- All - get all countries.
- Name - search countries by name, including the option of an exact or partial match.
- Capital - search countries by capital city. Uses a partial match.
- Currency - search countries by ISO 4217 currency code. Uses an exact match.
- Language - search countries by ISO 639-1 language code. Uses an exact match.
- Region - search countries by region: Africa, Americas, Asia, Europe, Oceania. Uses an exact match.
- RegionalBloc - search countries by regional bloc: EU, EFTA, CARICOM, PA etc. Uses an exact match.
- CallingCode - search countries by calling code. Uses an exact match.
- Code/List of Codes (method name is Codes) - search countries by ISO 3166-1 2-letter or 3-letter country codes. Uses an exact match.
package main
import (
"fmt"
"github.com/chriscross0/go-restcountries/v2"
)
func main(){
client := restcountries.New("YOUR_API_KEY")
client.SetApiRoot("http://api.countrylayer.com/v2") // if you are on the free plan, override the URL to use http because https is only supported on paid plans
// All with no fields filter (get all countries with all fields)
countries, err := client.All(restcountries.AllOptions{})
if err != nil {
fmt.Println(err)
} else {
fmt.Println("Total countries: ", len(countries)) // 250
fmt.Println("First country name: ", countries[0].Name) // Afghanistan
fmt.Println("First country capital: ", countries[0].Capital) // Kabul
}
}countries, err := client.Name(restcountries.NameOptions{
Name: "United States",
})
fmt.Println("Total countries: ", len(countries)) // 2
fmt.Println("First country name: ", countries[0].Name) // United States Minor Outlying Islands
fmt.Println("Second country name: ", countries[1].Name) // United States of Americacountries, err := client.Name(restcountries.NameOptions{
Name: "United States of America",
FullText: true, // true turns exact match on
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // United States of Americacountries, err := client.Capital(restcountries.CapitalOptions{
Name: "London",
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // United Kingdom of Great Britain and Northern Irelandcountries, err := client.Capital(restcountries.CapitalOptions{
Name: "Lon",
})
fmt.Println("Total countries: ", len(countries)) // 3
fmt.Println("First country name: ", countries[0].Name) // Malawi
fmt.Println("Second country name: ", countries[1].Name) // Svalbard and Jan Mayen
fmt.Println("Third country name: ", countries[2].Name) // United Kingdom of Great Britain and Northern Irelandcountries, err := client.Currency(restcountries.CurrencyOptions{
Currency: "IDR",
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // Indonesiacountries, err := client.Capital(restcountries.CurrencyOptions{
Currency: "SGD",
})
fmt.Println("Total countries: ", len(countries)) // 2
fmt.Println("First country name: ", countries[0].Name) // Brunei Darussalam
fmt.Println("Second country name: ", countries[1].Name) // Singaporecountries, err := client.Language(restcountries.LanguageOptions{
Language: "TG",
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // Tajikistancountries, err := client.Language(restcountries.LanguageOptions{
Language: "FF",
})
fmt.Println("Total countries: ", len(countries)) // 2
fmt.Println("First country name: ", countries[0].Name) // Burkina Faso
fmt.Println("Second country name: ", countries[1].Name) // Guineacountries, err := client.Region(restcountries.RegionOptions{
Region: "Oceania",
})
fmt.Println("Total countries: ", len(countries)) // 27
fmt.Println("First country name: ", countries[0].Name) // American Samoa
fmt.Println("Second country name: ", countries[1].Name) // Australiacountries, err := client.RegionalBloc(restcountries.RegionalBlocOptions{
RegionalBloc: "PA",
})
fmt.Println("Total countries: ", len(countries)) // 4
fmt.Println("First country name: ", countries[0].Name) // Chile
fmt.Println("Second country name: ", countries[1].Name) // Colombiacountries, err := client.CallingCode(restcountries.CallingCodeOptions{
CallingCode: "372",
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // Estoniacountries, err := client.CallingCode(restcountries.CallingCodeOptions{
CallingCode: "44",
})
fmt.Println("Total countries: ", len(countries)) // 4
fmt.Println("First country name: ", countries[0].Name) // Guernsey
fmt.Println("Second country name: ", countries[1].Name) // Isle of Mancountries, err := client.Codes(restcountries.CodesOptions{
Codes: []string{"CO"}, // single code
})
fmt.Println("Total countries: ", len(countries)) // 1
fmt.Println("First country name: ", countries[0].Name) // Colombiacountries, err := client.Codes(restcountries.CodesOptions{
Codes: []string{"CO", "GB"}, // multiple codes
})
fmt.Println("Total countries: ", len(countries)) // 2
fmt.Println("First country name: ", countries[0].Name) // Colombia
fmt.Println("Second country name: ", countries[1].Name) // United Kingdom of Great Britain and Northern IrelandBy default, all fields are returned from the API and populated to the Country type. Below is how to specify a whitelist of fields you would like and all others will not be returned. The Fields property is supported on the All(), Name(), Capital(), Currency(), Language(), Region(), RegionalBloc(), CallingCode() and Codes() methods, which return a slice of countries.
// Get all countries with fields filter, to include only the country Name and Capital
countries, err := client.All(restcountries.AllOptions{
Fields: []string{"Name", "Capital"},
})
fmt.Println(countries[0].Name) // Afghanistan
fmt.Println(countries[0].Capital) // Kabul
fmt.Println(countries[0].Region) // empty because this field was not requestedThe default timeout for the HTTP client is 0 (meaning no timeout). Use SetTimeout() to override the default timeout, using a time.Duration.
client := restcountries.New("YOUR_API_KEY")
client.SetTimeout(10 * time.Second) // 10 secondsThe default API root is https://api.countrylayer.com/v2. Use SetApiRoot() to override the root URL. If you are on the free plan then you will need to override the root URL to use http instead of https, because the free plan does not support https.
client := restcountries.New("YOUR_API_KEY")
client.SetApiRoot("http://api.countrylayer.com/v2")All fields in the v2 restcountries APi are supported. Below is the Country type:
type Country struct {
Name string `json:"name"`
TopLevelDomain []string `json:"topLevelDomain"`
Alpha2Code string `json:"alpha2Code"`
Alpha3Code string `json:"alpha3Code"`
CallingCodes []string `json:"callingCodes"`
Capital string `json:"capital"`
AltSpellings []string `json:"altSpellings"`
Region string `json:"region"`
Subregion string `json:"subregion"`
Population int `json:"population"`
Latlng []float64 `json:"latlng"`
Demonym string `json:"demonym"`
Area float64 `json:"area"`
Gini float64 `json:"gini"`
Timezones []string `json:"timezones"`
Borders []string `json:"borders"`
NativeName string `json:"nativeName"`
NumericCode string `json:"numericCode"`
Currencies []struct {
Code string `json:"code"`
Name string `json:"name"`
Symbol string `json:"symbol"`
} `json:"currencies"`
Languages []struct {
Iso6391 string `json:"iso639_1"`
Iso6392 string `json:"iso639_2"`
Name string `json:"name"`
NativeName string `json:"nativeName"`
} `json:"languages"`
Translations struct {
De string `json:"de"`
Es string `json:"es"`
Fr string `json:"fr"`
Ja string `json:"ja"`
It string `json:"it"`
Br string `json:"br"`
Pt string `json:"pt"`
Nl string `json:"nl"`
Hr string `json:"hr"`
Fa string `json:"fa"`
} `json:"translations"`
Flag string `json:"flag"`
RegionalBlocs []struct {
Acronym string `json:"acronym"`
Name string `json:"name"`
OtherAcronyms []string `json:"otherAcronyms"`
OtherNames []string `json:"otherNames"`
} `json:"regionalBlocs"`
Cioc string `json:"cioc"`
}