Documentation
¶
Overview ¶
Package geolocation resolves the client's IP address to a country, region and city (and, optionally, the country's main language).
Its entry point is New(Options), which returns a Handler that stores an *Info on the Context; read it back with Get, or look one up on demand with Fetch. Free for non-commercial use, no API key required.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Err = errors.New("geolocation error")
Err is the error returned when the geolocation information is not available. Usage:
if errors.Is(err, geolocation.Err) {
// handle the error err.Error().
}
Functions ¶
func New ¶
New returns a new geolocation middleware (custom implementation) based on the information retrieved by ip-api.com. It fetches the geolocation information for the client's IP address and stores it to the Iris Context. Retrieve the geolocation information using the `Get` function.
The default rate limit is 45 requests per minute (1,440 daily) for free version. Navigate through https://members.ip-api.com/#pricing to see the prices and the rate limits. Its paid plan with unlimited requests is very cheap compared to the rest (e.g. ipgeolocation.io).
Types ¶
type Info ¶
type Info struct {
Status string `json:"status"`
Country string `json:"country"`
CountryCode string `json:"countryCode"`
Region string `json:"region"`
RegionName string `json:"regionName"`
City string `json:"city"`
Zip string `json:"zip"`
Lat float64 `json:"lat"`
Lon float64 `json:"lon"`
Timezone string `json:"timezone"`
Isp string `json:"isp"`
Org string `json:"org"`
As string `json:"as"`
Query string `json:"query"`
Language string `json:"language"`
}
Info represents the geolocation information for an IP address.
func Fetch ¶
Fetch returns the geolocation information for the client's IP address. It returns the value already stored in the Iris Context, otherwise it performs a live lookup with the default options and stores the result in the Context. It returns an error if the information is not available. Use the `New` function to register the geolocation middleware or the `Get` function to read the stored value without performing a lookup.
type Options ¶
type Options struct {
// APIKey, when not empty and LocationClient is nil, points the location
// lookup at the paid HTTPS endpoint (https://pro.ip-api.com/json) with this
// key. It is ignored when LocationClient is set.
//
// Defaults to empty: the free, plaintext-HTTP endpoint is used.
APIKey string `yaml:"APIKey"`
// LocationClient is the HTTP client used to fetch geolocation information from ip-api.com.
//
// Absolutely free (with rate limiting) for non-commercial use, no API key required.
//
// Defaults to a client for http://ip-api.com/json rate-limited to 45 requests
// per minute (or the pro endpoint when APIKey is set).
LocationClient *client.Client `yaml:"-"`
// LanguageClient is the HTTP client used to fetch the language information from restcountries.com.
// Please consider donating if you are using it a lot.
//
// Defaults to a client for https://restcountries.com/v3.1/alpha.
// Set DisableLanguage to skip the language lookup entirely.
LanguageClient *client.Client `yaml:"-"`
// DisableLanguage skips the country-language lookup, so Info.Language is
// left empty and no request is sent to restcountries.com.
//
// Defaults to false.
DisableLanguage bool `yaml:"DisableLanguage"`
// Cache is the cache used to store the geolocation information.
//
// Defaults to cache.NewMemoryCache[Info](0).
// Set DisableCache to look up every request.
Cache cache.Cache[Info] `yaml:"-"`
// DisableCache turns the lookup cache off, so every request performs a live
// lookup. Mind the provider's rate limit.
//
// Defaults to false.
DisableCache bool `yaml:"DisableCache"`
}
Options is the configuration for the geolocation middleware. The zero value is valid and uses the free ip-api.com endpoint, restcountries.com for the language and an in-memory cache with no expiration.
It uses two different clients for fetching the geolocation information and the country's main language:
- ip-api.com API is used to fetch the geolocation information for the IP address,
- restcountries.com API is used to fetch the language for the country code.