geoip2-golang

Database Reuse

Always reuse database instances across requests. Do not open and close the database for every lookup, as this is expensive.

// Good: Create once, use many times
db, err := geoip2.Open("GeoIP2-City.mmdb")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

// Use db for multiple lookups...

Concurrent Usage

The Reader is safe for concurrent use by multiple goroutines.

Memory Usage

For applications needing only specific fields, consider using the lower-level maxminddb library with custom result structs to reduce memory allocation.

JSON Serialization

All result structs include JSON tags and support marshaling to JSON using the standard encoding/json package.

// JSON Serialization example
record, err := db.City(ip)
if err != nil {
    log.Fatal(err)
}

jsonData, err := json.Marshal(record)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(jsonData))

When performing lookups, follow these best practices:

1. Check for errors: All database methods return an error that must be handled.
2. Check HasData(): Even if no error is returned, the IP might not exist in the database. Always call record.HasData() before accessing fields.
3. Validate individual fields: Check if specific fields (like City.Names.English or Subdivisions) are empty or if arrays have elements before accessing them to avoid runtime issues.

package main

import (
	"fmt"
	"log"
	"net/netip"

	"github.com/oschwald/geoip2-golang/v2"
)

func main() {
	db, err := geoip2.Open("GeoIP2-City.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ip, err := netip.ParseAddr("10.0.0.1") // Private IP
	if err != nil {
		log.Fatal(err)
	}

	record, err := db.City(ip)
	if err != nil {
		log.Fatal(err)
	}

	// Always check if data was found
	if !record.HasData() {
		fmt.Println("No data found for this IP address")
		return
	}

	// Check individual fields before using them
	if record.City.Names.English != "" {
		fmt.Printf("City: %v\n", record.City.Names.English)
	} else {
		fmt.Println("City name not available")
	}

	// Check array bounds for subdivisions
	if len(record.Subdivisions) > 0 {
		fmt.Printf("Subdivision: %v\n", record.Subdivisions[0].Names.English)
	} else {
		fmt.Println("No subdivision data available")
	}

	fmt.Printf("Country: %v\n", record.Country.Names.English)
}

When upgrading to v2, several breaking changes must be addressed:

• Import Path: Update your imports from github.com/oschwald/geoip2-golang to github.com/oschwald/geoip2-golang/v2.
• IP Type: Switch from using net.IP to netip.Addr (from the net/netip package).
• Field Names: The field IsoCode has been renamed to ISOCode.
• Names Access: Access names via struct fields (e.g., .English) instead of map access (e.g., ["en"]).
• Data Validation: Use the HasData() method on the record to verify if data was actually found for the IP address.

// v1
import "github.com/oschwald/geoip2-golang"

ip := net.ParseIP("81.2.69.142")
record, err := db.City(ip)
cityName := record.City.Names["en"]

// v2
import "github.com/oschwald/geoip2-golang/v2"

ip, err := netip.ParseAddr("81.2.69.142")
if err != nil {
    // handle error
}
record, err := db.City(ip)
if !record.HasData() {
    // handle no data found
}
cityName := record.City.Names.English

The Country database provides country, continent, and EU membership information. Use db.Country(ip) to retrieve this data.

package main

import (
	"fmt"
	"log"
	"net/netip"

	"github.com/oschwald/geoip2-golang/v2"
)

func main() {
	db, err := geoip2.Open("GeoIP2-Country.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ip, err := netip.ParseAddr("81.2.69.142")
	if err != nil {
		log.Fatal(err)
	}

	record, err := db.Country(ip)
	if err != nil {
		log.Fatal(err)
	}

	if !record.HasData() {
		fmt.Println("No data found for this IP")
		return
	}

	fmt.Printf("Country: %v (%v)\n", record.Country.Names.English, record.Country.ISOCode)
	fmt.Printf("Continent: %v (%v)\n", record.Continent.Names.English, record.Continent.Code)
	fmt.Printf("Is in EU: %v\n", record.Country.IsInEuropeanUnion)
	fmt.Printf("Network: %v\n", record.Traits.Network)
	fmt.Printf("IP Address: %v\n", record.Traits.IPAddress)

	if record.RegisteredCountry.Names.English != "" {
		fmt.Printf("Registered Country: %v (%v)\n",
			record.RegisteredCountry.Names.English, record.RegisteredCountry.ISOCode)
	}
}

The Anonymous IP database identifies various types of anonymous and proxy networks, including VPNs, hosting providers, public/residential proxies, and Tor exit nodes. Use db.AnonymousIP(ip) to retrieve this data.

package main

import (
	"fmt"
	"log"
	"net/netip"

	"github.com/oschwald/geoip2-golang/v2"
)

func main() {
	db, err := geoip2.Open("GeoIP2-Anonymous-IP.mmdb")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ip, err := netip.ParseAddr("81.2.69.142")
	if err != nil {
		log.Fatal(err)
	}

	record, err := db.AnonymousIP(ip)
	if err != nil {
		log.Fatal(err)
	}

	if !record.HasData() {
		fmt.Println("No data found for this IP")
		return
	}

	fmt.Printf("Is Anonymous: %v\n", record.IsAnonymous)
	fmt.Printf("Is Anonymous VPN: %v\n", record.IsAnonymousVPN)
	fmt.Printf("Is Hosting Provider: %v\n", record.IsHostingProvider)
	fmt.Printf("Is Public Proxy: %v\n", record.IsPublicProxy)
	fmt.Printf("Is Residential Proxy: %v\n", record.IsResidentialProxy)
	fmt.Printf("Is Tor Exit Node: %v\n", record.IsTorExitNode)
	fmt.Printf("Network: %v\n", record.Network)
	fmt.Printf("IP Address: %v\n", record.IPAddress)
}