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"
"log"
"net"
"github.com/oschwald/geoip2-golang"
)
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.
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.
db, err := Open("test-data/test-data/GeoIP2-City-Test.mmdb")
if err != nil {
log.Panic(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.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)
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 ASN
- type AnonymousIP
- type City
- type ConnectionType
- type Country
- type Domain
- type Enterprise
- type ISP
- type InvalidMethodError
- type Reader
- func (r *Reader) ASN(ipAddress net.IP) (*ASN, 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) Enterprise(ipAddress net.IP) (*Enterprise, error)
- func (r *Reader) ISP(ipAddress net.IP) (*ISP, error)
- func (r *Reader) Metadata() maxminddb.Metadata
- type UnknownDatabaseTypeError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ASN ¶ added in v1.1.0
type ASN struct {
AutonomousSystemOrganization string `maxminddb:"autonomous_system_organization"`
AutonomousSystemNumber uint `maxminddb:"autonomous_system_number"`
}
The ASN struct corresponds to the data in the GeoLite2 ASN database.
type AnonymousIP ¶ added in v1.0.0
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 {
Names map[string]string `maxminddb:"names"`
GeoNameID uint `maxminddb:"geoname_id"`
} `maxminddb:"city"`
Postal struct {
Code string `maxminddb:"code"`
} `maxminddb:"postal"`
Continent struct {
Names map[string]string `maxminddb:"names"`
Code string `maxminddb:"code"`
GeoNameID uint `maxminddb:"geoname_id"`
} `maxminddb:"continent"`
Subdivisions []struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
} `maxminddb:"subdivisions"`
RepresentedCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
Type string `maxminddb:"type"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"represented_country"`
Country struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"country"`
RegisteredCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"registered_country"`
Location struct {
TimeZone string `maxminddb:"time_zone"`
Latitude float64 `maxminddb:"latitude"`
Longitude float64 `maxminddb:"longitude"`
MetroCode uint `maxminddb:"metro_code"`
AccuracyRadius uint16 `maxminddb:"accuracy_radius"`
} `maxminddb:"location"`
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 ¶ added in v1.0.0
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 {
Names map[string]string `maxminddb:"names"`
Code string `maxminddb:"code"`
GeoNameID uint `maxminddb:"geoname_id"`
} `maxminddb:"continent"`
Country struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"country"`
RegisteredCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"registered_country"`
RepresentedCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
Type string `maxminddb:"type"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `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 ¶ added in v1.0.0
type Domain struct {
Domain string `maxminddb:"domain"`
}
The Domain struct corresponds to the data in the GeoIP2 Domain database.
type Enterprise ¶ added in v1.3.0
type Enterprise struct {
Continent struct {
Names map[string]string `maxminddb:"names"`
Code string `maxminddb:"code"`
GeoNameID uint `maxminddb:"geoname_id"`
} `maxminddb:"continent"`
City struct {
Names map[string]string `maxminddb:"names"`
GeoNameID uint `maxminddb:"geoname_id"`
Confidence uint8 `maxminddb:"confidence"`
} `maxminddb:"city"`
Postal struct {
Code string `maxminddb:"code"`
Confidence uint8 `maxminddb:"confidence"`
} `maxminddb:"postal"`
Subdivisions []struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
Confidence uint8 `maxminddb:"confidence"`
} `maxminddb:"subdivisions"`
RepresentedCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
Type string `maxminddb:"type"`
GeoNameID uint `maxminddb:"geoname_id"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"represented_country"`
Country struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
Confidence uint8 `maxminddb:"confidence"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"country"`
RegisteredCountry struct {
Names map[string]string `maxminddb:"names"`
IsoCode string `maxminddb:"iso_code"`
GeoNameID uint `maxminddb:"geoname_id"`
Confidence uint8 `maxminddb:"confidence"`
IsInEuropeanUnion bool `maxminddb:"is_in_european_union"`
} `maxminddb:"registered_country"`
Traits struct {
AutonomousSystemOrganization string `maxminddb:"autonomous_system_organization"`
ConnectionType string `maxminddb:"connection_type"`
Domain string `maxminddb:"domain"`
ISP string `maxminddb:"isp"`
MobileCountryCode string `maxminddb:"mobile_country_code"`
MobileNetworkCode string `maxminddb:"mobile_network_code"`
Organization string `maxminddb:"organization"`
UserType string `maxminddb:"user_type"`
AutonomousSystemNumber uint `maxminddb:"autonomous_system_number"`
StaticIPScore float64 `maxminddb:"static_ip_score"`
IsAnonymousProxy bool `maxminddb:"is_anonymous_proxy"`
IsLegitimateProxy bool `maxminddb:"is_legitimate_proxy"`
IsSatelliteProvider bool `maxminddb:"is_satellite_provider"`
} `maxminddb:"traits"`
Location struct {
TimeZone string `maxminddb:"time_zone"`
Latitude float64 `maxminddb:"latitude"`
Longitude float64 `maxminddb:"longitude"`
MetroCode uint `maxminddb:"metro_code"`
AccuracyRadius uint16 `maxminddb:"accuracy_radius"`
} `maxminddb:"location"`
}
The Enterprise struct corresponds to the data in the GeoIP2 Enterprise database.
type ISP ¶ added in v1.0.0
type ISP struct {
AutonomousSystemOrganization string `maxminddb:"autonomous_system_organization"`
ISP string `maxminddb:"isp"`
MobileCountryCode string `maxminddb:"mobile_country_code"`
MobileNetworkCode string `maxminddb:"mobile_network_code"`
Organization string `maxminddb:"organization"`
AutonomousSystemNumber uint `maxminddb:"autonomous_system_number"`
}
The ISP struct corresponds to the data in the GeoIP2 ISP database.
type InvalidMethodError ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶
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 used directly; any modification of it after opening the database will result in errors while reading from the database.
func Open ¶
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 ¶ added in v1.1.0
ASN takes an IP address as a net.IP struct and returns a ASN struct and/or an error.
func (*Reader) AnonymousIP ¶ added in v1.0.0
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 ¶
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 ¶
Close unmaps the database file from virtual memory and returns the resources to the system.
func (*Reader) ConnectionType ¶ added in v1.0.0
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 ¶
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 ¶ added in v1.0.0
Domain takes an IP address as a net.IP struct and returns a Domain struct and/or an error.
func (*Reader) Enterprise ¶ added in v1.3.0
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.
type UnknownDatabaseTypeError ¶ added in v1.0.0
type UnknownDatabaseTypeError struct {
DatabaseType string
}
UnknownDatabaseTypeError is returned when an unknown database type is opened.
func (UnknownDatabaseTypeError) Error ¶ added in v1.0.0
func (e UnknownDatabaseTypeError) Error() string
Source Files