README

GeoIP2 Reader for Go

PkgGoDev

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"])
	if len(record.Subdivisions) > 0 {
		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.

Expand ▾ Collapse ▴

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 structs 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.

      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

      Examples

      Constants

      This section is empty.

      Variables

      This section is empty.

      Functions

      This section is empty.

      Types

      type ASN

      type ASN struct {
      	AutonomousSystemNumber       uint   `maxminddb:"autonomous_system_number"`
      	AutonomousSystemOrganization string `maxminddb:"autonomous_system_organization"`
      }

        The ASN struct corresponds to the data in the GeoLite2 ASN database.

        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"`
        	IsResidentialProxy bool `maxminddb:"is_residential_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"`
          		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
          		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"`
          		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
          		IsoCode           string            `maxminddb:"iso_code"`
          		Names             map[string]string `maxminddb:"names"`
          	} `maxminddb:"registered_country"`
          	RepresentedCountry struct {
          		GeoNameID         uint              `maxminddb:"geoname_id"`
          		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
          		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"`
              		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
              		IsoCode           string            `maxminddb:"iso_code"`
              		Names             map[string]string `maxminddb:"names"`
              	} `maxminddb:"country"`
              	RegisteredCountry struct {
              		GeoNameID         uint              `maxminddb:"geoname_id"`
              		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
              		IsoCode           string            `maxminddb:"iso_code"`
              		Names             map[string]string `maxminddb:"names"`
              	} `maxminddb:"registered_country"`
              	RepresentedCountry struct {
              		GeoNameID         uint              `maxminddb:"geoname_id"`
              		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
              		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 Enterprise

                  type Enterprise struct {
                  	City struct {
                  		Confidence uint8             `maxminddb:"confidence"`
                  		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"`
                  		Confidence        uint8             `maxminddb:"confidence"`
                  		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
                  	} `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"`
                  		Confidence uint8  `maxminddb:"confidence"`
                  	} `maxminddb:"postal"`
                  	RegisteredCountry struct {
                  		GeoNameID         uint              `maxminddb:"geoname_id"`
                  		IsoCode           string            `maxminddb:"iso_code"`
                  		Names             map[string]string `maxminddb:"names"`
                  		Confidence        uint8             `maxminddb:"confidence"`
                  		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
                  	} `maxminddb:"registered_country"`
                  	RepresentedCountry struct {
                  		GeoNameID         uint              `maxminddb:"geoname_id"`
                  		IsInEuropeanUnion bool              `maxminddb:"is_in_european_union"`
                  		IsoCode           string            `maxminddb:"iso_code"`
                  		Names             map[string]string `maxminddb:"names"`
                  		Type              string            `maxminddb:"type"`
                  	} `maxminddb:"represented_country"`
                  	Subdivisions []struct {
                  		Confidence uint8             `maxminddb:"confidence"`
                  		GeoNameID  uint              `maxminddb:"geoname_id"`
                  		IsoCode    string            `maxminddb:"iso_code"`
                  		Names      map[string]string `maxminddb:"names"`
                  	} `maxminddb:"subdivisions"`
                  	Traits struct {
                  		AutonomousSystemNumber       uint    `maxminddb:"autonomous_system_number"`
                  		AutonomousSystemOrganization string  `maxminddb:"autonomous_system_organization"`
                  		ConnectionType               string  `maxminddb:"connection_type"`
                  		Domain                       string  `maxminddb:"domain"`
                  		IsAnonymousProxy             bool    `maxminddb:"is_anonymous_proxy"`
                  		IsLegitimateProxy            bool    `maxminddb:"is_legitimate_proxy"`
                  		IsSatelliteProvider          bool    `maxminddb:"is_satellite_provider"`
                  		ISP                          string  `maxminddb:"isp"`
                  		StaticIPScore                float64 `maxminddb:"static_ip_score"`
                  		Organization                 string  `maxminddb:"organization"`
                  		UserType                     string  `maxminddb:"user_type"`
                  	} `maxminddb:"traits"`
                  }

                    The Enterprise struct corresponds to the data in the GeoIP2 Enterprise 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 modification 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) ASN

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

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

                                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) Enterprise

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

                                              Enterprise takes an IP address as a net.IP struct and returns an Enterprise struct and/or an error. This is intended to be used with the GeoIP2 Enterprise database.

                                              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

                                                    Source Files