geoip2

README

GeoIP2 Reader for Go

This library reads MaxMind GeoLite2 and GeoIP2 databases.

This library is built using the Go maxminddb reader. All data for the database record is decoded using this library. If you only need several fields, you may get superior performance by using maxminddb's Lookup directly with a result struct that only contains the required fields. (See example_test.go in the maxminddb repository for an example of this.)

Installation

go get github.com/oschwald/geoip2-golang

Usage

See GoDoc for documentation and examples.

Example

package main

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

func main() {
    db, err := geoip2.Open("GeoIP2-City.mmdb")
    if err != nil {
            log.Fatal(err)
    }
    defer db.Close()
    // If you are using strings that may be invalid, check that ip is not nil
    ip := net.ParseIP("81.2.69.142")
    record, err := db.City(ip)
    if err != nil {
            log.Fatal(err)
    }
    fmt.Printf("Portuguese (BR) city name: %v\n", record.City.Names["pt-BR"])
    fmt.Printf("English subdivision name: %v\n", record.Subdivisions[0].Names["en"])
    fmt.Printf("Russian country name: %v\n", record.Country.Names["ru"])
    fmt.Printf("ISO country code: %v\n", record.Country.IsoCode)
    fmt.Printf("Time zone: %v\n", record.Location.TimeZone)
    fmt.Printf("Coordinates: %v, %v\n", record.Location.Latitude, record.Location.Longitude)
    // Output:
    // Portuguese (BR) city name: Londres
    // English subdivision name: England
    // Russian country name: Великобритания
    // ISO country code: GB
    // Time zone: Europe/London
    // Coordinates: 51.5142, -0.0931
}

Testing

Make sure you checked out test data submodule:

git submodule init
git submodule update

Execute test suite:

go test

Contributing

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

License

This is free software, licensed under the ISC license.

Documentation

Overview

Package geoip2 provides an easy-to-use API for the MaxMind GeoIP2 and GeoLite2 databases; this package does not support GeoIP Legacy databases.

The strucs provided by this package match the internal structure of the data in the MaxMind databases.

See github.com/oschwald/maxminddb-golang for more advanced used cases.

Example

Example provides a basic example of using the API. Use of the Country method is analogous to that of the City method.

db, err := Open("test-data/test-data/GeoIP2-City-Test.mmdb")
if err != nil {
	log.Fatal(err)
}
defer db.Close()
// If you are using strings that may be invalid, check that ip is not nil
ip := net.ParseIP("81.2.69.142")
record, err := db.City(ip)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Portuguese (BR) city name: %v\n", record.City.Names["pt-BR"])
fmt.Printf("English subdivision name: %v\n", record.Subdivisions[0].Names["en"])
fmt.Printf("Russian country name: %v\n", record.Country.Names["ru"])
fmt.Printf("ISO country code: %v\n", record.Country.IsoCode)
fmt.Printf("Time zone: %v\n", record.Location.TimeZone)
fmt.Printf("Coordinates: %v, %v\n", record.Location.Latitude, record.Location.Longitude)

Output:

Portuguese (BR) city name: Londres
English subdivision name: England
Russian country name: Великобритания
ISO country code: GB
Time zone: Europe/London
Coordinates: 51.5142, -0.0931

Index

• type AnonymousIP
• type City
• type ConnectionType
• type Country
• type Domain
• type ISP
• type InvalidMethodError
  • func (e InvalidMethodError) Error() string
• type Reader
  • func FromBytes(bytes []byte) (*Reader, error)
  • func Open(file string) (*Reader, error)
  • func (r *Reader) AnonymousIP(ipAddress net.IP) (*AnonymousIP, error)
  • func (r *Reader) City(ipAddress net.IP) (*City, error)
  • func (r *Reader) Close() error
  • func (r *Reader) ConnectionType(ipAddress net.IP) (*ConnectionType, error)
  • func (r *Reader) Country(ipAddress net.IP) (*Country, error)
  • func (r *Reader) Domain(ipAddress net.IP) (*Domain, error)
  • func (r *Reader) ISP(ipAddress net.IP) (*ISP, error)
  • func (r *Reader) Metadata() maxminddb.Metadata
• type UnknownDatabaseTypeError
  • func (e UnknownDatabaseTypeError) Error() string

Examples

• Package

Types

type AnonymousIP

type AnonymousIP struct {
	IsAnonymous       bool `maxminddb:"is_anonymous"`
	IsAnonymousVPN    bool `maxminddb:"is_anonymous_vpn"`
	IsHostingProvider bool `maxminddb:"is_hosting_provider"`
	IsPublicProxy     bool `maxminddb:"is_public_proxy"`
	IsTorExitNode     bool `maxminddb:"is_tor_exit_node"`
}

The AnonymousIP struct corresponds to the data in the GeoIP2 Anonymous IP database.

type City

type City struct {
	City struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"city"`
	Continent struct {
		Code      string            `maxminddb:"code"`
		GeoNameID uint              `maxminddb:"geoname_id"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"continent"`
	Country struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"country"`
	Location struct {
		AccuracyRadius uint16  `maxminddb:"accuracy_radius"`
		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"`
	RegisteredCountry struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"registered_country"`
	RepresentedCountry struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
		Type      string            `maxminddb:"type"`
	} `maxminddb:"represented_country"`
	Subdivisions []struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"subdivisions"`
	Traits struct {
		IsAnonymousProxy    bool `maxminddb:"is_anonymous_proxy"`
		IsSatelliteProvider bool `maxminddb:"is_satellite_provider"`
	} `maxminddb:"traits"`
}

The City struct corresponds to the data in the GeoIP2/GeoLite2 City databases.

type ConnectionType

type ConnectionType struct {
	ConnectionType string `maxminddb:"connection_type"`
}

The ConnectionType struct corresponds to the data in the GeoIP2 Connection-Type database.

type Country

type Country struct {
	Continent struct {
		Code      string            `maxminddb:"code"`
		GeoNameID uint              `maxminddb:"geoname_id"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"continent"`
	Country struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"country"`
	RegisteredCountry struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
	} `maxminddb:"registered_country"`
	RepresentedCountry struct {
		GeoNameID uint              `maxminddb:"geoname_id"`
		IsoCode   string            `maxminddb:"iso_code"`
		Names     map[string]string `maxminddb:"names"`
		Type      string            `maxminddb:"type"`
	} `maxminddb:"represented_country"`
	Traits struct {
		IsAnonymousProxy    bool `maxminddb:"is_anonymous_proxy"`
		IsSatelliteProvider bool `maxminddb:"is_satellite_provider"`
	} `maxminddb:"traits"`
}

The Country struct corresponds to the data in the GeoIP2/GeoLite2 Country databases.

type Domain

type Domain struct {
	Domain string `maxminddb:"domain"`
}

The Domain struct corresponds to the data in the GeoIP2 Domain database.

type ISP

type ISP struct {
	AutonomousSystemNumber       uint   `maxminddb:"autonomous_system_number"`
	AutonomousSystemOrganization string `maxminddb:"autonomous_system_organization"`
	ISP                          string `maxminddb:"isp"`
	Organization                 string `maxminddb:"organization"`
}

The ISP struct corresponds to the data in the GeoIP2 ISP database.

type InvalidMethodError

type InvalidMethodError struct {
	Method       string
	DatabaseType string
}

InvalidMethodError is returned when a lookup method is called on a database that it does not support. For instance, calling the ISP method on a City database.

func (InvalidMethodError) Error

func (e InvalidMethodError) Error() string

type Reader

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

Reader holds the maxminddb.Reader struct. It can be created using the Open and FromBytes functions.

func FromBytes

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

FromBytes takes a byte slice corresponding to a GeoIP2/GeoLite2 database file and returns a Reader struct or an error. Note that the byte slice is use directly; any modication of it after opening the database will result in errors while reading from the database.

func Open

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

Open takes a string path to a file and returns a Reader struct 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) AnonymousIP

func (r *Reader) AnonymousIP(ipAddress net.IP) (*AnonymousIP, error)

AnonymousIP takes an IP address as a net.IP struct and returns a AnonymousIP struct and/or an error.

func (*Reader) City

func (r *Reader) City(ipAddress net.IP) (*City, error)

City takes an IP address as a net.IP struct and returns a City struct and/or an error. Although this can be used with other databases, this method generally should be used with the GeoIP2 or GeoLite2 City databases.

func (*Reader) Close

func (r *Reader) Close() error

Close unmaps the database file from virtual memory and returns the resources to the system.

func (*Reader) ConnectionType

func (r *Reader) ConnectionType(ipAddress net.IP) (*ConnectionType, error)

ConnectionType takes an IP address as a net.IP struct and returns a ConnectionType struct and/or an error

func (*Reader) Country

func (r *Reader) Country(ipAddress net.IP) (*Country, error)

Country takes an IP address as a net.IP struct and returns a Country struct and/or an error. Although this can be used with other databases, this method generally should be used with the GeoIP2 or GeoLite2 Country databases.

func (*Reader) Domain

func (r *Reader) Domain(ipAddress net.IP) (*Domain, error)

Domain takes an IP address as a net.IP struct and returns a Domain struct and/or an error

func (*Reader) ISP

func (r *Reader) ISP(ipAddress net.IP) (*ISP, error)

ISP takes an IP address as a net.IP struct and returns a ISP struct and/or an error

func (*Reader) Metadata

func (r *Reader) Metadata() maxminddb.Metadata

Metadata takes no arguments and returns a struct containing metadata about the MaxMind database in use by the Reader.

type UnknownDatabaseTypeError

type UnknownDatabaseTypeError struct {
	DatabaseType string
}

UnknownDatabaseTypeError is returned when an unknown database type is opened.

func (UnknownDatabaseTypeError) Error

func (e UnknownDatabaseTypeError) Error() string