geo

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:

1. https://github.com/biter777/countries
2. https://github.com/oschwald/geoip2-golang

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

1. Support easy lookup for geo information from MaxMind DB using IP string.
2. Support both alpha2 country code and alpha3 country code.
3. Support any io.Reader for user to provide the MaxMind mmdb file.
4. Support easy access of the database metadata info like build time and version.
5. Provide default return value of ZZ and ZZZ as 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"
    "github.com/blockthrough/geo"
)

// 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 := geo.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 function directly if you want to get alpha3 code
    fmt.Sprintf("country 3-letter code", geo.CountryAlpha2CodeToAlpha3Code(country.CountryAlpha2Code()))
}

Documentation

Index

• Constants
• func CountryAlpha2CodeToAlpha3Code(alpha2Code string) string
• func CountryAlpha3CodeToAlpha2Code(alpha3Code string) string
• type Reader
  • func NewMaxMind(b []byte) (*Reader, error)
  • func NewMaxMindReader(r io.Reader) (*Reader, error)
  • func (m *Reader) BuildTimestamp() time.Time
  • func (m *Reader) Close()
  • func (m *Reader) Country(ip net.IP) (*country, error)
  • func (m *Reader) CountryByIPString(ip string) (*country, error)
  • func (m *Reader) IsTestDB() bool
  • func (m *Reader) Version() string

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

Functions

func CountryAlpha2CodeToAlpha3Code

func CountryAlpha2CodeToAlpha3Code(alpha2Code string) string

CountryAlpha2CodeToAlpha3Code - get a 3-letter country code if a country identified by 2-letter country code

func CountryAlpha3CodeToAlpha2Code

func CountryAlpha3CodeToAlpha2Code(alpha3Code string) string

CountryAlpha3CodeToAlpha2Code - get a 2-letter country code if a country identified by 3-letter country code

Types

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 NewMaxMind(b []byte) (*Reader, error)

func NewMaxMindReader

func NewMaxMindReader(r io.Reader) (*Reader, error)

func (*Reader) BuildTimestamp

func (m *Reader) BuildTimestamp() time.Time

BuildTimestamp - the timestamp when the MaxMind DB is built

func (*Reader) Close

func (m *Reader) Close()

func (*Reader) Country

func (m *Reader) Country(ip net.IP) (*country, error)

func (*Reader) CountryByIPString

func (m *Reader) CountryByIPString(ip string) (*country, error)

func (*Reader) IsTestDB

func (m *Reader) IsTestDB() bool

func (*Reader) Version

func (m *Reader) Version() string

Version - the opinionated semanic version for the underlying MaxMind DB in the format of v<major_version>.<minor_version>