Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


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.


Version published


# freegeoip

This is the source code of the freegeoip software. It contains both
the web server that empowers, and a package for the
[Go]( programming language that enables any web server
to support IP geolocation with a simple and clean API.

See for details about geolocation.

Developers looking for the Go API can skip to the [Package freegeoip](#packagefreegeoip)
section below.

## Running

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](#serveroptions) below for more information on configuring
the server.

### Docker

Install Docker on Ubuntu 14.04 LTS:

sudo apt-get install

Install Docker on CentOS 7:

yum install docker

Run the freegeoip web server:

docker run --net=host --restart=always -d fiorix/freegeoip


curl localhost:8080/json/

See the **API** section below for details.

### Other Linux, OS X, or FreeBSD

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.

<a name="serveroptions">
### Server Options

You 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, 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/`.

## Database

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.

## API

The freegeoip API is served by endpoints that encode the response
in different formats.



Returns the geolocation information of your own IP address, the source
IP address of the connection.

You can pass a different IP or hostname:


To lookup the geolocation of `` after resolving its IP address,
which might be IPv4 or IPv6.

Responses can also be encoded as JSONP, by adding the `callback` parameter:


Same semantics are available for the `/xml/{ip}` and `/csv/{ip}` endpoints
except the callback parameter.

## Metrics and profiling

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.

<a name="packagefreegeoip">
## Package freegeoip

The freegeoip package for the Go programming language provides two APIs:

- A database API that requires zero maintenance of the IP database;
- A geolocation `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.

[![Build Status](](

### Features

- Zero maintenance

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.

- DevOps friendly

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.

- Extensible

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 There's also an interface for
crafting your own HTTP responses encoded in any format.

### Install

Download the package:

	go get -d

Install the web server:

	go install

Test coverage is quite good and tests may help you find the stuff you need.


Last updated on 03 Dec 2016

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc