geoip2

README

GeoIP2 Reader for Go

This library reads MaxMind GeoLite2 and GeoIP2 databases.

This is not an official MaxMind API.

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"
    "net"
)

func main() {
    db, err := geoip2.Open("GeoIP2-City.mmdb")
    if err != nil {
            panic(err)
    }
    // 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 {
            panic(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)

    db.Close()
    // 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
}

Notes

This uses the maxminddb library.

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

Overview

Package geoip2 provides a wrapper around the maxminddb package for easy use with the MaxMind GeoIP2 and GeoLite2 databases. The records for the IP address is returned from this package as well-formed structures that match the internal layout of data from MaxMind.

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 {
	panic(err)
}
// 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 {
	panic(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)

db.Close()

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 City
• type Country
• type Reader
  • func FromBytes(bytes []byte) (*Reader, error)
  • func Open(file string) (*Reader, error)
  • func (r *Reader) City(ipAddress net.IP) (*City, error)
  • func (r *Reader) Close()
  • func (r *Reader) Country(ipAddress net.IP) (*Country, error)

Examples

• Package

Types

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 {
		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 structure corresponds to the data in the GeoIP2/GeoLite2 City databases.

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 structure corresponds to the data in the GeoIP2/GeoLite2 Country databases.

type Reader

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

Reader holds the maxminddb.Reader structure. It should be created using the Open function.

func FromBytes

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

FromBytes takes a byte slice corresponding to a GeoIP2/GeoLite2 database file and returns a Reader structure or an error.

func Open

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

Open takes a string path to a 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) 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()

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

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.