1# GeoIP2 Reader for Go #
2
3[![PkgGoDev](https://pkg.go.dev/badge/github.com/oschwald/geoip2-golang)](https://pkg.go.dev/github.com/oschwald/geoip2-golang)
4
5This library reads MaxMind [GeoLite2](http://dev.maxmind.com/geoip/geoip2/geolite2/)
6and [GeoIP2](http://www.maxmind.com/en/geolocation_landing) databases.
7
8This library is built using
9[the Go maxminddb reader](https://github.com/oschwald/maxminddb-golang).
10All data for the database record is decoded using this library. If you only
11need several fields, you may get superior performance by using maxminddb's
12`Lookup` directly with a result struct that only contains the required fields.
13(See [example_test.go](https://github.com/oschwald/maxminddb-golang/blob/master/example_test.go)
14in the maxminddb repository for an example of this.)
15
16## Installation ##
17
18```
19go get github.com/oschwald/geoip2-golang
20```
21
22## Usage ##
23
24[See GoDoc](http://godoc.org/github.com/oschwald/geoip2-golang) for
25documentation and examples.
26
27## Example ##
28
29```go
30package main
31
32import (
33	"fmt"
34	"github.com/oschwald/geoip2-golang"
35	"log"
36	"net"
37)
38
39func main() {
40	db, err := geoip2.Open("GeoIP2-City.mmdb")
41	if err != nil {
42		log.Fatal(err)
43	}
44	defer db.Close()
45	// If you are using strings that may be invalid, check that ip is not nil
46	ip := net.ParseIP("81.2.69.142")
47	record, err := db.City(ip)
48	if err != nil {
49		log.Fatal(err)
50	}
51	fmt.Printf("Portuguese (BR) city name: %v\n", record.City.Names["pt-BR"])
52	if len(record.Subdivisions) > 0 {
53		fmt.Printf("English subdivision name: %v\n", record.Subdivisions[0].Names["en"])
54	}
55	fmt.Printf("Russian country name: %v\n", record.Country.Names["ru"])
56	fmt.Printf("ISO country code: %v\n", record.Country.IsoCode)
57	fmt.Printf("Time zone: %v\n", record.Location.TimeZone)
58	fmt.Printf("Coordinates: %v, %v\n", record.Location.Latitude, record.Location.Longitude)
59	// Output:
60	// Portuguese (BR) city name: Londres
61	// English subdivision name: England
62	// Russian country name: Великобритания
63	// ISO country code: GB
64	// Time zone: Europe/London
65	// Coordinates: 51.5142, -0.0931
66}
67```
68
69## Testing ##
70
71Make sure you checked out test data submodule:
72
73```
74git submodule init
75git submodule update
76```
77
78Execute test suite:
79
80```
81go test
82```
83
84## Contributing ##
85
86Contributions welcome! Please fork the repository and open a pull request
87with your changes.
88
89## License ##
90
91This is free software, licensed under the ISC license.
92