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.

Status

This API should be functional, particularly when used with the geoip2 API. That said, the following work remains to be done:

• Docs need to be written.
• The code should be made idiomatic.
• Although IPv4 addresses work, the code to speed up IPv4 lookups is not working as ParseIP always seems to return 16 bytes.
• The error handling, particularly related to reflection, should be improved.
• The speed of the API could be improved. On my computer, I get about 20,000 lookups per second with this API as compared to 50,000 lookups per second with the Java API.

Pull requests and patches are encouraged.

Example Decoding to a Struct

package main

import (
    "fmt"
    "log"
    "github.com/oschwald/maxminddb-golang"
    "geoip2"
    "net"
)

func main() {
    db, err := maxminddb.Open("GeoLite2-City.mmdb")
    if err != nil {
        log.Fatal(err)
    }
    ip := net.ParseIP("1.1.1.1")

    var record geoip2.City // Or any appropriate struct
    err := db.Lookup(ip, &record)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(record)
    db.Close()
}

Example Decoding to an Interface

package main

import (
    "fmt"
    "log"
    "github.com/oschwald/maxminddb-golang"
    "net"
)

func main() {
    db, err := maxminddb.Open("GeoLite2-City.mmdb")
    if err != nil {
        log.Fatal(err)
    }
    ip := net.ParseIP("1.1.1.1")

    var record interface{}
    err := db.Lookup(ip, &record)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(record)
    db.Close()
}

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

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"`
}

type Reader

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

func FromBytes

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

func Open

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

func (*Reader) Close

func (r *Reader) Close()

func (*Reader) Lookup

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