{"id":13414035,"url":"https://github.com/chriscross0/go-restcountries","last_synced_at":"2025-03-14T20:30:58.839Z","repository":{"id":57620488,"uuid":"391698278","full_name":"chriscross0/go-restcountries","owner":"chriscross0","description":"Go wrapper for the REST Countries API.","archived":false,"fork":false,"pushed_at":"2021-10-27T15:38:43.000Z","size":93,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-07-31T20:53:19.394Z","etag":null,"topics":["api-client","api-wrapper","countries","countries-api","go","golang","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chriscross0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-01T17:49:51.000Z","updated_at":"2024-05-26T18:11:49.000Z","dependencies_parsed_at":"2022-09-02T16:35:41.551Z","dependency_job_id":null,"html_url":"https://github.com/chriscross0/go-restcountries","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscross0%2Fgo-restcountries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscross0%2Fgo-restcountries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscross0%2Fgo-restcountries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscross0%2Fgo-restcountries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chriscross0","download_url":"https://codeload.github.com/chriscross0/go-restcountries/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243642068,"owners_count":20323953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-wrapper","countries","countries-api","go","golang","rest-api"],"created_at":"2024-07-30T20:01:55.899Z","updated_at":"2025-03-14T20:30:58.534Z","avatar_url":"https://github.com/chriscross0.png","language":"Go","funding_links":[],"categories":["Third-party APIs","第三方api","Utility"],"sub_categories":["Utility/Miscellaneous","实用程序/Miscellaneous","Fail injection","HTTP Clients"],"readme":"Go REST Countries\r\n=================\r\n\r\n[![GoDoc](https://godoc.org/github.com/chriscross0/go-restcountries?status.svg)](http://godoc.org/github.com/chriscross0/go-restcountries)\r\n[![Build Status](https://travis-ci.com/chriscross0/go-restcountries.svg?branch=master)](https://travis-ci.org/chriscross0/go-restcountries)\r\n[![Coverage Status](https://coveralls.io/repos/github/chriscross0/go-restcountries/badge.svg?branch=master)](https://coveralls.io/github/chriscross0/go-restcountries?branch=master)\r\n[![Go Report Card](https://goreportcard.com/badge/github.com/chriscross0/go-restcountries)](https://goreportcard.com/report/github.com/chriscross0/go-restcountries)\r\n\r\ngo-restcountries is a wrapper for the [Countrylayer REST Countries API](https://countrylayer.com/) (formerly restcountries.eu), written in Go. The latest (v2) version of the API is used.\r\n\r\nNote: 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.\r\n\r\n## Supported API methods (all methods of the v2 API are supported)\r\n\r\n- All - get all countries.\r\n- Name - search countries by name, including the option of an exact or partial match.\r\n- Capital - search countries by capital city. Uses a partial match.\r\n- Currency - search countries by ISO 4217 currency code. Uses an exact match.\r\n- Language - search countries by ISO 639-1 language code. Uses an exact match.\r\n- Region - search countries by region: Africa, Americas, Asia, Europe, Oceania. Uses an exact match.\r\n- RegionalBloc - search countries by regional bloc: EU, EFTA, CARICOM, PA etc. Uses an exact match.\r\n- CallingCode - search countries by calling code. Uses an exact match.\r\n- 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.\r\n\r\n## Usage\r\n\r\n### Get all countries\r\n\r\n```go\r\npackage main\r\n\r\nimport (\r\n\t\"fmt\"\r\n\t\"github.com/chriscross0/go-restcountries/v2\"\r\n)\r\n\r\nfunc main(){\r\n\tclient := restcountries.New(\"YOUR_API_KEY\")\r\n\tclient.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\r\n\r\n\t// All with no fields filter (get all countries with all fields)\r\n\tcountries, err := client.All(restcountries.AllOptions{})\r\n\r\n\tif err != nil {\r\n\t\tfmt.Println(err)\r\n\t} else {\r\n\t\tfmt.Println(\"Total countries: \", len(countries)) // 250\r\n\t\tfmt.Println(\"First country name: \", countries[0].Name) // Afghanistan\r\n\t\tfmt.Println(\"First country capital: \", countries[0].Capital) // Kabul\r\n\t}\r\n}\r\n\r\n```\r\n\r\n### Search countries by name - partial match\r\n\r\n```go\r\ncountries, err := client.Name(restcountries.NameOptions{\r\n\tName: \"United States\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 2\r\nfmt.Println(\"First country name: \", countries[0].Name) // United States Minor Outlying Islands\r\nfmt.Println(\"Second country name: \", countries[1].Name) // United States of America\r\n```\r\n\r\n### Search countries by name - exact match\r\n\r\n```go\r\ncountries, err := client.Name(restcountries.NameOptions{\r\n\tName: \"United States of America\",\r\n\tFullText: true, // true turns exact match on\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // United States of America\r\n```\r\n\r\n### Search countries by capital city - partial match with single country found\r\n\r\n```go\r\ncountries, err := client.Capital(restcountries.CapitalOptions{\r\n\tName: \"London\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // United Kingdom of Great Britain and Northern Ireland\r\n```\r\n\r\n### Search countries by capital city - partial match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.Capital(restcountries.CapitalOptions{\r\n\tName: \"Lon\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 3\r\nfmt.Println(\"First country name: \", countries[0].Name) // Malawi\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Svalbard and Jan Mayen\r\nfmt.Println(\"Third country name: \", countries[2].Name) // United Kingdom of Great Britain and Northern Ireland\r\n```\r\n\r\n### Search countries by currency code - exact match with single country found\r\n\r\n```go\r\ncountries, err := client.Currency(restcountries.CurrencyOptions{\r\n\tCurrency: \"IDR\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // Indonesia\r\n```\r\n\r\n### Search countries by currency code - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.Capital(restcountries.CurrencyOptions{\r\n\tCurrency: \"SGD\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 2\r\nfmt.Println(\"First country name: \", countries[0].Name) // Brunei Darussalam\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Singapore\r\n```\r\n\r\n### Search countries by language code - exact match with single country found\r\n\r\n```go\r\ncountries, err := client.Language(restcountries.LanguageOptions{\r\n\tLanguage: \"TG\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // Tajikistan\r\n```\r\n\r\n### Search countries by language code - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.Language(restcountries.LanguageOptions{\r\n\tLanguage: \"FF\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 2\r\nfmt.Println(\"First country name: \", countries[0].Name) // Burkina Faso\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Guinea\r\n```\r\n\r\n### Search countries by region - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.Region(restcountries.RegionOptions{\r\n\tRegion: \"Oceania\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 27\r\nfmt.Println(\"First country name: \", countries[0].Name) // American Samoa\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Australia\r\n```\r\n\r\n### Search countries by regional bloc - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.RegionalBloc(restcountries.RegionalBlocOptions{\r\n\tRegionalBloc: \"PA\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 4\r\nfmt.Println(\"First country name: \", countries[0].Name) // Chile\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Colombia\r\n```\r\n\r\n### Search countries by calling code - exact match with single country found\r\n\r\n```go\r\ncountries, err := client.CallingCode(restcountries.CallingCodeOptions{\r\n\tCallingCode: \"372\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // Estonia\r\n```\r\n\r\n### Search countries by calling code - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.CallingCode(restcountries.CallingCodeOptions{\r\n\tCallingCode: \"44\",\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 4\r\nfmt.Println(\"First country name: \", countries[0].Name) // Guernsey\r\nfmt.Println(\"Second country name: \", countries[1].Name) // Isle of Man\r\n```\r\n\r\n### Search countries by country code - exact match with single country found\r\n\r\n```go\r\ncountries, err := client.Codes(restcountries.CodesOptions{\r\n\tCodes: []string{\"CO\"}, // single code\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 1\r\nfmt.Println(\"First country name: \", countries[0].Name) // Colombia\r\n```\r\n\r\n### Search countries by country code - exact match with multiple countries found\r\n\r\n```go\r\ncountries, err := client.Codes(restcountries.CodesOptions{\r\n\tCodes: []string{\"CO\", \"GB\"}, // multiple codes\r\n})\r\n\r\nfmt.Println(\"Total countries: \", len(countries)) // 2\r\nfmt.Println(\"First country name: \", countries[0].Name) // Colombia\r\nfmt.Println(\"Second country name: \", countries[1].Name) // United Kingdom of Great Britain and Northern Ireland\r\n```\r\n\r\n### Fields Filtering\r\n\r\nBy 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.\r\n\r\n```go\r\n// Get all countries with fields filter, to include only the country Name and Capital\r\ncountries, err := client.All(restcountries.AllOptions{\r\n\tFields: []string{\"Name\", \"Capital\"},\r\n})\r\n\r\nfmt.Println(countries[0].Name) // Afghanistan\r\nfmt.Println(countries[0].Capital) // Kabul\r\nfmt.Println(countries[0].Region) // empty because this field was not requested\r\n```\r\n\r\n## Configuration\r\n\r\n### `SetTimeout()`\r\n\r\nThe default timeout for the HTTP client is `0` (meaning no timeout). Use `SetTimeout()` to override the default timeout, using a [`time.Duration`](https://pkg.go.dev/time#Duration).\r\n\r\n```go\r\nclient := restcountries.New(\"YOUR_API_KEY\")\r\nclient.SetTimeout(10 * time.Second) // 10 seconds\r\n```\r\n\r\n### `SetApiRoot()`\r\n\r\nThe 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.\r\n\r\n```go\r\nclient := restcountries.New(\"YOUR_API_KEY\")\r\nclient.SetApiRoot(\"http://api.countrylayer.com/v2\")\r\n```\r\n\r\n\r\n## Supported Fields\r\n\r\nAll fields in the v2 restcountries APi are supported. Below is the Country type:\r\n\r\n```go\r\ntype Country struct {\r\n\tName           string    `json:\"name\"`\r\n\tTopLevelDomain []string  `json:\"topLevelDomain\"`\r\n\tAlpha2Code     string    `json:\"alpha2Code\"`\r\n\tAlpha3Code     string    `json:\"alpha3Code\"`\r\n\tCallingCodes   []string  `json:\"callingCodes\"`\r\n\tCapital        string    `json:\"capital\"`\r\n\tAltSpellings   []string  `json:\"altSpellings\"`\r\n\tRegion         string    `json:\"region\"`\r\n\tSubregion      string    `json:\"subregion\"`\r\n\tPopulation     int       `json:\"population\"`\r\n\tLatlng         []float64 `json:\"latlng\"`\r\n\tDemonym        string    `json:\"demonym\"`\r\n\tArea           float64   `json:\"area\"`\r\n\tGini           float64   `json:\"gini\"`\r\n\tTimezones      []string  `json:\"timezones\"`\r\n\tBorders        []string  `json:\"borders\"`\r\n\tNativeName     string    `json:\"nativeName\"`\r\n\tNumericCode    string    `json:\"numericCode\"`\r\n\tCurrencies     []struct {\r\n\t\tCode   string `json:\"code\"`\r\n\t\tName   string `json:\"name\"`\r\n\t\tSymbol string `json:\"symbol\"`\r\n\t} `json:\"currencies\"`\r\n\tLanguages []struct {\r\n\t\tIso6391    string `json:\"iso639_1\"`\r\n\t\tIso6392    string `json:\"iso639_2\"`\r\n\t\tName       string `json:\"name\"`\r\n\t\tNativeName string `json:\"nativeName\"`\r\n\t} `json:\"languages\"`\r\n\tTranslations struct {\r\n\t\tDe string `json:\"de\"`\r\n\t\tEs string `json:\"es\"`\r\n\t\tFr string `json:\"fr\"`\r\n\t\tJa string `json:\"ja\"`\r\n\t\tIt string `json:\"it\"`\r\n\t\tBr string `json:\"br\"`\r\n\t\tPt string `json:\"pt\"`\r\n\t\tNl string `json:\"nl\"`\r\n\t\tHr string `json:\"hr\"`\r\n\t\tFa string `json:\"fa\"`\r\n\t} `json:\"translations\"`\r\n\tFlag          string `json:\"flag\"`\r\n\tRegionalBlocs []struct {\r\n\t\tAcronym       string   `json:\"acronym\"`\r\n\t\tName          string   `json:\"name\"`\r\n\t\tOtherAcronyms []string `json:\"otherAcronyms\"`\r\n\t\tOtherNames    []string `json:\"otherNames\"`\r\n\t} `json:\"regionalBlocs\"`\r\n\tCioc string `json:\"cioc\"`\r\n}\r\n\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriscross0%2Fgo-restcountries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchriscross0%2Fgo-restcountries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriscross0%2Fgo-restcountries/lists"}