A MaxMind® GeoIP microservice and lookup tool written in GO, and pulling ideas from:
- https://github.com/klauspost/geoip-service
- https://github.com/twisted1919/geoip-go
- https://github.com/oschwald/geoip2-golang
- https://github.com/mitchellh/cli
Note: this project is not affiliated with MaxMind, and only provides a tool to facilitate data lookup from maxmind specific geoip databases.
$ go get -u github.com/rabbitt/maxmind
$ cd $GOPATH/src/github.com/rabbitt/maxmind
$ make bootstrap
$ make maxmind
- GeoLite2-City.mmdb from MaxMind
This package provides a single binary maxmind
providing both, lookup
, and server
functionality. Basic help
information can be gleaned by typing maxmind --help
. More specific help information can be found by issuing
--help
to the relevant subcommand.
To list GeoIP data for one, or more, IPs, use the following:
$ maxmind lookup -f <path to GeoLite2-City.mmdb> 123.123.123.123 8.8.8.8 8.8.4.4
[ 123.123.123.123 ]---------------------->
Continent: [Asia (AS)]
Country: [China (CN)]
Subdivision: [Beijing (BJ)]
City: [Beijing]
Location:
Coordinates: [39.9289, 116.3883 (20)]
Timezone: [Asia/Shanghai]
[ 8.8.8.8 ]---------------------->
Continent: [North America (NA)]
Country: [United States (US)]
Location:
Coordinates: [37.7510, -97.8220 (1000)]
[ 8.8.4.4 ]---------------------->
Continent: [North America (NA)]
Country: [United States (US)]
Location:
Coordinates: [37.7510, -97.8220 (1000)]
The server has three routes that it listens for requests on:
GET /ping
- responds with 200 and pongHEAD /ping
- responds with 200 onlyGET /ip/:ip
- responds with geodata (as JSON) for the requested ip
Configuration can be passed on the command line, or put into a JSON encoded file using the same long form names as those of the options listed below:
- -c, --config.file
- Path to JSON encoded file containing server configuration.
- -i, --sever.ip
- IP Address for the service to bind to (default: 127.0.0.1)
- -p, --server.port
- Port for service to bind to (default: 8000)
- -f, --database.file
- Path to the MaxMind database file (default: /var/lib/maxminddb/GeoLite2-City.mmdb)
- -t, --cache.ttl
- How long to rcache response data before refetching it from the database (0 disables, default: 3600.0)
- -T, --worker.threads
- Number of worker threads to handle incoming requests (default: Number of CPU processes)
Starting up requires, at a minimum, the path to the MaxMind database file:
$ bin/maxmind server -f /var/lib/maxminddb/GeoLite2-City.mmdb
INFO: Configuration:
INFO: Bind Address: [ 127.0.0.1:8000 ]
INFO: Cache TTL: [ 3600.00 seconds ]
INFO: Worker Threads: [ 8 ]
INFO: Database File: [ /private/var/lib/maxminddb/GeoLite2-City.mmdb ]
INFO: Caching enabled; will cache requests for 3600.00 seconds
INFO: Listening on 127.0.0.1:8000 ...
Example output from a client request for ip 123.123.123.123
:
# $ curl -s http://127.0.0.1:8000/ip/123.123.123.123 | jq
{
"status": "success",
"message": "OK",
"data": {
"city": {
"name": "Beijing"
},
"continent": {
"code": "AS",
"name": "Asia"
},
"country": {
"iso_code": "CN",
"name": "China"
},
"location": {
"accuracy_radius": 20,
"latitude": 39.9289,
"longitude": 116.3883,
"time_zone": "Asia/Shanghai"
},
"postal": {},
"registered_country": {
"iso_code": "CN",
"name": "China"
},
"represented_country": {},
"subdivisions": [
{
"iso_code": "BJ",
"name": "Beijing"
}
],
"subdivision": {
"iso_code": "BJ",
"name": "Beijing"
},
"traits": {}
}
}