github.com/arthurpro/freegeoip
Package freegeoip provides an API for searching the geolocation of IP addresses. It uses a database that can be either a local file or a remote resource from a URL. Local databases are monitored by fsnotify and reloaded when the file is either updated or overwritten. Remote databases are automatically downloaded and updated in background so you can focus on using the API and not managing the database.
Readme
This is the source code of the freegeoip software. It contains both the web server that empowers freegeoip.net, and a package for the Go programming language that enables any web server to support IP geolocation with a simple and clean API.
See http://en.wikipedia.org/wiki/Geolocation for details about geolocation.
Developers looking for the Go API can skip to the Package freegeoip section below.
This section is for people who desire to run the freegeoip web server on their own infrastructure. The easiest and most generic way of doing this is by using Docker.
See the Server Options below for more information on configuring the server.
Install Docker on Ubuntu 14.04 LTS:
sudo apt-get install docker.io
Install Docker on CentOS 7:
yum install docker
Run the freegeoip web server:
docker run --net=host --restart=always -d fiorix/freegeoip
Test:
curl localhost:8080/json/1.2.3.4
See the API section below for details.
There are pre-compiled binaries available. You'll have to set up your own init scripts for your system.
There is also a Chef cookbook to deploy it automatically.
### Server OptionsYou can configure the freegeoip web server to listen on a port other than the default 8080, and also listen on HTTPS by passing an ip:port and X.509 certificate and key files.
These and many other options are described in the help. If you're using Docker, you can see them like this:
docker run --rm -it fiorix/freegeoip --help
By default, the Docker image of freegeoip does not provide the web page from freegeiop.net, it only provides the API.
If you want to serve that page, you can pass the -public=/var/www
parameter in the command line. You can also tell Docker to mount that
directory as a volume on the host machine and have it serve your own
page, using Docker's -v parameter.
If the freegeoip web server is running behind a proxy or load
balancer, you have to run it passing the -use-x-forwarded-for
parameter and provide the X-Forwarded-For HTTP header so the web
server is capable of using the source IP address of the connection
to perform geolocation lookups when an IP is not provided to
the API, e.g. /json/ vs /json/1.2.3.4.
The current implementation uses the free GeoLite2 database from MaxMind.
In the past we had databases from other providers, and at some point even our own database comprised of different sources. This means it might change in the future.
If you have purchased the commercial database from MaxMind, you can point the freegeoip web server or Go API to the URL of it, or local file, and the server will use it.
In case of files on disk, you can replace with a new version and the freegeoip software will load it automatically. URLs are frequently checked in background, and if a new version of the database is available it is loaded automatically also.
The freegeoip API is served by endpoints that encode the response in different formats.
Example:
curl freegeoip.net/json/
Returns the geolocation information of your own IP address, the source IP address of the connection.
You can pass a different IP or hostname:
curl freegeoip.net/json/github.com
To lookup the geolocation of github.com after resolving its IP address,
which might be IPv4 or IPv6.
Responses can also be encoded as JSONP, by adding the callback parameter:
curl freegeoip.net/json/?callback=foobar
Same semantics are available for the /xml/{ip} and /csv/{ip} endpoints
except the callback parameter.
The freegeoip web server can provide metrics about its usage, and also supports runtime profiling.
Both are disabled by default, but can be enabled by passing the
-internal-server=:8081 parameter in the command line. Metrics are
generated for Prometheus and can be queried
at /metrics even with curl.
HTTP pprof is available at /debug/pprof and the examples from
the pprof package work.
The freegeoip package for the Go programming language provides two APIs:
http.Handler that can be used/served by any http server.tl;dr if all you want is code then see the example_test.go file.
Otherwise check out the godoc reference.
The DB object alone can download an IP database file from the internet and service lookups to your program right away. It will auto-update the file in background and always magically work.
If you do care about the database and have the commercial version of the MaxMind database, you can update the database file with your program running and the DB object will load it in background. You can focus on your stuff.
Besides the database part, the package provides an http.Handler object
that you can add to your HTTP server to service IP geolocation lookups with
the same simplistic API of freegeoip.net. There's also an interface for
crafting your own HTTP responses encoded in any format.
Download the package:
go get -d github.com/fiorix/freegeoip/...
Install the web server:
go install github.com/fiorix/freegeoip/cmd/freegeoip
Test coverage is quite good and tests may help you find the stuff you need.
FAQs
Package freegeoip provides an API for searching the geolocation of IP addresses. It uses a database that can be either a local file or a remote resource from a URL. Local databases are monitored by fsnotify and reloaded when the file is either updated or overwritten. Remote databases are automatically downloaded and updated in background so you can focus on using the API and not managing the database.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.