Skip to content

Latest commit

 

History

History
102 lines (70 loc) · 3 KB

README.md

File metadata and controls

102 lines (70 loc) · 3 KB
Raw

Topographer

CI Code Coverage Go Reference

Fast and lenient self-hosted IP geolocation service.

Sometimes you need to detect regions and cities of different IPs. There are a bunch of databases and free services available but you need to have a code which works with these database or deal with limitations of these services. For example, ipinfo.io or freegeoip.net limit your queries.

Sometimes you need your own service which responds with country/city and does not have such limitations. Most of such services are based on free versions of geolocation databases so it makes sense to have a free self-hosted service which you can simply plug into your infrastructure.

Also, if you ever deal with IP geolocation you may know it is awfully imprecise. There are many situations when one database detects one city, another - slightly different location. Also, if you deal with non-residential IPs you may know that a lot of hosters and clouds have a weird route setup so you may have differences even in countries!

Just look at this example: https://bgpview.io/ip/191.96.13.80 Which country does this IP belong?

This service goes in slightly different way: it uses a couple of databases, collects their results, combine and consolidate results and return a final one.

It queries all providers (or a limited set of them), picks the most popular country. Within this country group, it picks the most popular city and returns this tuple as a result.

Building

Building is trivial.

  1. Install Golang;
  2. Run go get github.com/9seconds/topographer

or if you want to build from sources:

$ git clone https://github.com/9seconds/topographer
$ cd topographer
$ go build

or simple build Docker container

$ docker build -t topographer .

Installing

Installation is simple as

$ go get github.com/9seconds/topographer

(but if you want, you can find prebuilt binaries on releases page)

We also have Docker images in both DockerHub and Github Container Registry:

$ docker pull nineseconds/topographer

and

$ docker pull ghcr.io/9seconds/topographer:master

Running the application

A binary has a single cli flag: -config.

$ topographer -config /path/to/config.hjson

or if you run with docker, just put config as /config.hjson there:

$ docker run -v /path/to/local/config.hjson:/config.hjson -p 8000:80 nineseconds/topographer

API

Please see OpenAPI specification.