README
¶
Geo Information Library For Go
The library currently supports reads MaxMind GeoIP2 database and provide a thin decorator/helper function on the returned data for easy retrival and decoration on top of the geo info provided by MaxMind. It also provides a normalized way to represent the geo info in standard ISO format the scenario of unknown.
The implemenation of this library is based upon other 2 open source repositories:
Goal
The library is visioned to support more features related to processing of the geo info data in the future. That means, support reading from multiple geo database providers and expose more helpers on the data for commonly encountered user scenarios.
Features
- Support easy lookup for geo information from MaxMind DB using IP string.
- Support both alpha2 country code and alpha3 country code.
- Support any
io.Readerfor user to provide the MaxMind mmdb file. - Support easy access of the database metadata info like build time and version.
- Provide default return value of
ZZandZZZas specified in ISO standard if the country could not be found by the input IP using helper functions.
Installation
GOPRIVATE=github.com/blockthrough get github.com/blockthrough/geo
Since it is not an open-sourced repository yet, use GOPRIVATE to make sure go installer knows it is a private module. You also need to make sure you have correct git access to the private module.
How To Use
Read Maxmind DB and LookUp Geo With IP
package main
import (
"embed"
"fmt"
)
////go:embed <your_maxmind_db_file_path>
var embedFS embed.FS
func main() {
file, err := embedFS.Open("<your_maxmind_db_file_path>")
if err != nil {
t.Fatal(fmt.Errorf("embedFS.Open: %w", err))
}
maximind, err := NewMaxMindReader(file)
if err != nil {
t.Fatal(fmt.Errorf("NewMaxMindn: %w", err))
}
// check the meta information of the database
fmt.Sprintf("test db: %t",maxmind.IsTestDB())
fmt.Sprintf("db build time: %s",maxmind.BuildTimestamp())
fmt.Sprintf("db version: %s",maxmind.Version())
// you can pass ipv4 or ipv6 address
country, err := maxmind.Country("127.0.0.1")
if err != nil {
fmt.Error("err:%s",err)
}
fmt.Sprintf("unknown country: %s", country.isUnknown())) // is the country unknown?
fmt.Sprintf("country code: %s", country.CountryAlpha2Code()) // 2-letter country code
fmt.Sprintf("country 3-letter code: %s", country.CountryAlpha3Code()) // 3-letter country code
fmt.Sprintf("continent code: %s", country.ContinentCode()) // 2-letter continent code
// you can also use adapter directly if we want to have alpha3 code
fmt.Sprintf("country 3-letter code", CountryAlpha2CodeToAlpha3Code(country.CountryAlpha2Code()))
}
Documentation
¶
Index ¶
Constants ¶
const UnknownAlpha2Code = "ZZ" // ZZ is the commonly recoginized country/continient code for unknown, as specified in ISO alpha2
const UnknownAlpha3Code = "ZZZ" // ZZZ is derived from "ZZ" to represent 3 letter country/continent code for unknown, as specified in ISO alpha3
Variables ¶
This section is empty.
Functions ¶
func CountryAlpha2CodeToAlpha3Code ¶
CountryAlpha2CodeToAlpha3Code - get a 3-letter country code if a country identified by 2-letter country code
func CountryAlpha3CodeToAlpha2Code ¶
CountryAlpha3CodeToAlpha2Code - get a 2-letter country code if a country identified by 3-letter country code
Types ¶
type Country ¶
type Country geoip2.Country
Country - a type definition on geoip2.Country data struct while providing heloer functions to retrieve certain data in convinent way and additional country data maxmind db does not provide user is expected not to directly modify it.
func (Country) ContinentCode ¶
ContinentCode - a helper function to retrieve 2-letter ISO code for country from maxmind DB
func (Country) CountryAlpha2Code ¶
CountryAlpha2Code - a helper function to retrieve 2-letter ISO code for country from maxmind DB, if the country is found, the code will be "ZZ"
func (Country) CountryAlpha3Code ¶
CountryAlpha3Code - return 3-letter ISO code for country
type Reader ¶
type Reader struct {
*geoip2.Reader
}
Reader - a thin wrapper which provides helper function to parse information provided by embedded geoip2.Reader
func NewMaxMind ¶
func (*Reader) BuildTimestamp ¶
BuildTimestamp - the timestamp when the MaxMind DB is built
Source Files
Directories