maxminddb

README

MaxMind DB Reader for Go

This is a Go reader for the MaxMind DB format. This can be used to read GeoLite2 and GeoIP2 databases.

This is not an official MaxMind API.

Installation

go get github.com/oschwald/maxminddb-golang

Usage

See GoDoc for documentation and examples.

Examples

See GoDoc or example_test.go for examples.

Contributing

Contributions welcome! Please fork the repository and open a pull request with your changes.

License

This is free software, licensed under the Apache License, Version 2.0.

Documentation

Index

• type Metadata
• type Reader
  • func FromBytes(buffer []byte) (*Reader, error)
  • func Open(file string) (*Reader, error)
  • func (r *Reader) Close()
  • func (r *Reader) Lookup(ipAddress net.IP, result interface{}) error

Examples

• Reader.Lookup (Interface)
• Reader.Lookup (Struct)

Types

type Metadata

type Metadata struct {
	BinaryFormatMajorVersion uint              `maxminddb:"binary_format_major_version"`
	BinaryFormatMinorVersion uint              `maxminddb:"binary_format_minor_version"`
	BuildEpoch               uint              `maxminddb:"build_epoch"`
	DatabaseType             string            `maxminddb:"database_type"`
	Description              map[string]string `maxminddb:"description"`
	IPVersion                uint              `maxminddb:"ip_version"`
	Languages                []string          `maxminddb:"languages"`
	NodeCount                uint              `maxminddb:"node_count"`
	RecordSize               uint              `maxminddb:"record_size"`
}

Metadata holds the metadata decoded from the MaxMind DB file. In particular in has the format version, the build time as Unix epoch time, the database type and description, the IP version supported, and a slice of the natural languages included.

type Reader

type Reader struct {
	Metadata Metadata
	// contains filtered or unexported fields
}

Reader holds the data corresponding to the MaxMind DB file. Its only public field is Metadata, which contains the metadata from the MaxMind DB file.

func FromBytes

func FromBytes(buffer []byte) (*Reader, error)

FromBytes takes a byte slice corresponding to a MaxMind DB file and returns a Reader structure or an error.

func Open

func Open(file string) (*Reader, error)

Open takes a string path to a MaxMind DB file and returns a Reader structure or an error. The database file is opened using a memory map. Use the Close method on the Reader object to return the resources to the system.

func (*Reader) Close

func (r *Reader) Close()

Close unmaps the database file from virtual memory and returns the resources to the system. If called on a Reader opened using FromBytes, this method does nothing.

func (*Reader) Lookup

func (r *Reader) Lookup(ipAddress net.IP, result interface{}) error

Lookup takes an IP address as a net.IP structure and a pointer to the result value to decode into. The result value pointed to must be a data value that corresponds to a record in the database. This may include a struct representation of the data, a map capable of holding the data or an empty interface{} value.

If result is a pointer to a struct, the struct need not include a field for every value that may be in the database. If a field is not present in the structure, the decoder will not decode that field, reducing the time required to decode the record.

Currently the decoder expect most data types to correspond exactly (e.g., a uint64 database type must be decoded into a uint64 Go type). In the future, this may be made more flexible.

Example (Interface)

This example demonstrates how to decode to an interface{}

db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
if err != nil {
	log.Fatal(err)
}
defer db.Close()

ip := net.ParseIP("81.2.69.142")

var record interface{}
err = db.Lookup(ip, &record)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%v", record)

Example (Struct)

This example shows how to decode to a struct

db, err := maxminddb.Open("test-data/test-data/GeoIP2-City-Test.mmdb")
if err != nil {
	log.Fatal(err)
}
defer db.Close()

ip := net.ParseIP("81.2.69.142")

var record onlyCountry // Or any appropriate struct
err = db.Lookup(ip, &record)
if err != nil {
	log.Fatal(err)
}
fmt.Print(record.Country.IsoCode)

Output:

GB