freegeoip: Index | Examples | Files | Directories

package freegeoip

import ""

Package freegeoip provides an API for searching the geolocation of IP addresses. It uses a database that can be either a local file or a remote resource from a URL.

Local databases are monitored by fsnotify and reloaded when the file is either updated or overwritten.

Remote databases are automatically downloaded and updated in background so you can focus on using the API and not managing the database.



Package Files

db.go doc.go


var (
    // ErrUnavailable may be returned by DB.Lookup when the database
    // points to a URL and is not yet available because it's being
    // downloaded in background.
    ErrUnavailable = errors.New("no database available")

    // MaxMindDB is the URL of the free MaxMind GeoLite2 database.
    MaxMindDB = ""

func MaxMindUpdateURL Uses

func MaxMindUpdateURL(hostname, productID, userID, licenseKey string) (string, error)

MaxMindUpdateURL generates the URL for MaxMind paid databases.

type DB Uses

type DB struct {
    // contains filtered or unexported fields

DB is the IP geolocation database.

func Open Uses

func Open(dsn string) (*DB, error)

Open creates and initializes a DB from a local file.

The database file is monitored by fsnotify and automatically reloads when the file is updated or overwritten.


db, err := Open("./testdata.gz")
if err != nil {
var result customQuery
err = db.Lookup(net.ParseIP(""), &result)
if err != nil {
defer db.Close()
log.Printf("%#v", result)

func OpenURL Uses

func OpenURL(url string, updateInterval, maxRetryInterval time.Duration) (*DB, error)

OpenURL creates and initializes a DB from a URL. It automatically downloads and updates the file in background, and keeps a local copy on $TMPDIR.


updateInterval := 24 * time.Hour
maxRetryInterval := time.Hour
db, err := OpenURL(MaxMindDB, updateInterval, maxRetryInterval)
if err != nil {
defer db.Close()
select {
case <-db.NotifyOpen():
    // Wait for the db to be downloaded.
case err := <-db.NotifyError():
var result customQuery
err = db.Lookup(net.ParseIP(""), &result)
if err != nil {
log.Printf("%#v", result)

func (*DB) Close Uses

func (db *DB) Close()

Close closes the database.

func (*DB) Date Uses

func (db *DB) Date() time.Time

Date returns the UTC date the database file was last modified. If no database file has been opened the behaviour of Date is undefined.

func (*DB) Lookup Uses

func (db *DB) Lookup(addr net.IP, result interface{}) error

Lookup performs a database lookup of the given IP address, and stores the response into the result value. The result value must be a struct with specific fields and tags as described here:

See the DefaultQuery for an example of the result struct.

func (*DB) NotifyClose Uses

func (db *DB) NotifyClose() <-chan struct{}

NotifyClose returns a channel that is closed when the database is closed.

func (*DB) NotifyError Uses

func (db *DB) NotifyError() (errChan <-chan error)

NotifyError returns a channel that notifies when an error occurs while downloading or reloading a DB that points to a URL.

func (*DB) NotifyInfo Uses

func (db *DB) NotifyInfo() <-chan string

NotifyInfo returns a channel that notifies informational messages while downloading or reloading.

func (*DB) NotifyOpen Uses

func (db *DB) NotifyOpen() (filename <-chan string)

NotifyOpen returns a channel that notifies when a new database is loaded or reloaded. This can be used to monitor background updates when the DB points to a URL.

type DefaultQuery Uses

type DefaultQuery struct {
    Continent struct {
        Names map[string]string `maxminddb:"names"`
    }   `maxminddb:"continent"`
    Country struct {
        ISOCode string            `maxminddb:"iso_code"`
        Names   map[string]string `maxminddb:"names"`
    }   `maxminddb:"country"`
    Region []struct {
        ISOCode string            `maxminddb:"iso_code"`
        Names   map[string]string `maxminddb:"names"`
    }   `maxminddb:"subdivisions"`
    City struct {
        Names map[string]string `maxminddb:"names"`
    }   `maxminddb:"city"`
    Location struct {
        Latitude  float64 `maxminddb:"latitude"`
        Longitude float64 `maxminddb:"longitude"`
        MetroCode uint    `maxminddb:"metro_code"`
        TimeZone  string  `maxminddb:"time_zone"`
    }   `maxminddb:"location"`
    Postal struct {
        Code string `maxminddb:"code"`
    }   `maxminddb:"postal"`

DefaultQuery is the default query used for database lookups.


apiserverPackage apiserver provides the freegeoip web server.

Package freegeoip imports 17 packages (graph) and is imported by 17 packages. Updated 2020-01-27. Refresh now. Tools for package owners.