IP geolocation web server

freegeoip

NOTE: as of April 2018 this repository is no longer active. Please visit https://github.com/apilayer/freegeoip/ for the current version.


Deploy

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.

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. All examples below use Docker.

Docker

Install Docker

Docker has install instructions for many platforms, including

Run the API in a container

docker run --restart=always -p 8080:8080 -d fiorix/freegeoip

Test

curl localhost:8080/json/1.2.3.4
# => {"ip":"1.2.3.4","country_code":"US","country_name":"United States", # ...

Other Linux, OS X, FreeBSD, and Windows

There are pre-compiled binaries available.

Production configuration

For production workloads you may want to use different configuration for the freegeoip web server, for example:

  • Enabling the "internal server" for collecting metrics and profiling/tracing the freegeoip web server on demand
  • Monitoring the internal server using Prometheus, or exporting your metrics to New Relic
  • Serving the freegeoip API over HTTPS (TLS) using your own certificates, or provisioned automatically using LetsEncrypt.org
  • Configuring HSTS to restrict your browser clients to always use HTTPS
  • Configuring the read and write timeouts to avoid stale clients consuming server resources
  • Configuring the freegeoip web server to read the client IP (for logs, etc) from the X-Forwarded-For header when running behind a reverse proxy
  • Configuring CORS to restrict access to your API to specific domains
  • Configuring a specific endpoint path prefix other than the default "/" (thus /json, /xml, /csv) to serve the API alongside other APIs on the same host
  • Optimizing your round trips by enabling TCP Fast Open on your OS and the freegeoip web server
  • Setting up usage limits (quotas) for your clients (per client IP) based on requests per time interval; we support various backends such as in-memory map (for single instance), or redis or memcache for distributed deployments
  • Serve the default GeoLite2 City free database that is downloaded and updated automatically in background on a configurable schedule, or
  • Serve the commercial GeoIP2 City database from MaxMind, either as a local file that you provide and update periodically (so the server can reload it), or configured to be downloaded periodically using your API key

See the Server Options section below for more information on configuring the server.

For automation, check out the freegeoip chef cookbook or the (legacy) Ansible Playbook for Ubuntu 14.04 LTS.

Server Options

To see all the available options, use the -help option:

docker run --rm -it fiorix/freegeoip -help

If you're using LetsEncrypt.org to provision your TLS certificates, you have to listen for HTTPS on port 443. Following is an example of the server listening on 3 different ports: metrics + pprof (8888), http (80), and https (443):

docker run -p 8888:8888 -p 80:8080 -p 443:8443 -d fiorix/freegeoip \
	-internal-server=:8888 \
	-http=:8080 \
	-https=:8443 \
	-hsts=max-age=31536000 \
	-letsencrypt \
	-letsencrypt-hosts=myfancydomain.io

You can configure the freegeiop web server via command line flags or environment variables. The names of environment variables are the same for command line flags, but prefixed with FREEGEOIP, all upperscase, separated by underscores. If you want to use environment variables instead:

$ cat prod.env
FREEGEOIP_INTERNAL_SERVER=:8888
FREEGEOIP_HTTP=:8080
FREEGEOIP_HTTPS=:8443
FREEGEOIP_HSTS=max-age=31536000
FREEGEOIP_LETSENCRYPT=true
FREEGEOIP_LETSENCRYPT_HOSTS=myfancydomain.io

$ docker run --env-file=prod.env -p 8888:8888 -p 80:8080 -p 443:8443 -d fiorix/freegeoip

By default, HTTP/2 is enabled over HTTPS. You can disable by passing the -http2=false flag.

Also, 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 reverse proxy or load balancer, you have to run it passing the -use-x-forwarded-for parameter and provide the X-Forwarded-For HTTP header in all requests. This is for the freegeoip web server be able to log the client IP, and to perform geolocation lookups when an IP is not provided to the API, e.g. /json/ (uses client IP) vs /json/1.2.3.4.

Database

The current implementation uses the free GeoLite2 City database from MaxMind.

In the past we had databases from other providers, and at some point even our own database comprised of data from 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, for dev) to the URL containing the file, or local file, and the server will use it.

In case of files on disk, you can replace the file with a newer version and the freegeoip web server will reload it automatically in background. If instead of a file you use a URL (the default), we periodically check the URL in background to see if there's a new database version available, then download the reload it automatically.

All responses from the freegeiop API contain the date that the database was downloaded in the X-Database-Date HTTP header.

API

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. For example, to lookup the geolocation of github.com the server resolves the name first, then uses the first IP address available, which might be IPv4 or IPv6:

curl freegeoip.net/json/github.com

Same semantics are available for the /xml/{ip} and /csv/{ip} endpoints.

JSON responses can be encoded as JSONP, by adding the callback parameter:

curl freegeoip.net/json/?callback=foobar

The callback parameter is ignored on all other endpoints.

Metrics and profiling

The freegeoip web server can provide metrics about its usage, and also supports runtime profiling and tracing.

Both are disabled by default, but can be enabled by passing the -internal-server 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 documentation should work on the freegeiop web server.

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.

GoDoc Build Status GoReportCard

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

Install

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 test code may help you find the stuff you need.

Owner
Comments
  • Online service disruption

    Online service disruption

    I cannot continue running the public API on freegeoip.net at the moment. Will transition the DNS to a friend's server (@gleicon) on Digital Ocean in the next hour, and shut down my servers.

    If you desperately need freegeoip, please download the software and run yourself.

  • Enable CORS on server

    Enable CORS on server

    Hi,

    I would like to access your public API through a web application written in full JS.

    In this case, you need to enable CORS on the server.

    See http://enable-cors.org/ for more information.

    Do you think you will be able to enable this on your public API ?

    Regards,

  • How to Use Both HTTP and HTTPS with Custom Ports and HTML Content Protected by Let's Encrypt SSL Certificates?

    How to Use Both HTTP and HTTPS with Custom Ports and HTML Content Protected by Let's Encrypt SSL Certificates?

    According to the documentation from the docker package, shouldn't I be able to:

    Listen to HTTP requests on all IPs on port 13333 Listen to HTTPS requests on all IPs on port 13334 Serve static HTML content from the "/var/www/geoservices" directory if no API format is specified (basically the "/" page)? (does it try to load index.html by default?) Use SSL certificates provided by Let's Encrypt for the hosts of "www.domainhere.com,domain.com"

    Using this command:

    docker run --restart=always -p 13333:13334 -d fiorix/freegeoip -http 0.0.0.0:13333 -https 0.0.0.0:13334 -public /var/www/geoservices -letsencrypt -letsencrypt-email [email protected] -letsencrypt-hosts www.domainhere.com,domain.com
    

    What am I doing wrong? The documentation doesn't seem to go into this much detail. Using the above command results in neither HTTP or HTTPS working.

    Any help is appreciated.

  • SSL certificate does not validate peer list

    SSL certificate does not validate peer list

    Hey guys. Follow up from my previous request to support SSL: https://github.com/fiorix/freegeoip/issues/22

    Seems the certificate you purchased is not from a known provider.

    ➜  ~  curl https://freegeoip.net/geoip/8.8.8.8
    curl: (60) Peer certificate cannot be authenticated with known CA certificates
    More details here: http://curl.haxx.se/docs/sslcerts.html
    
    curl performs SSL certificate verification by default, using a "bundle"
     of Certificate Authority (CA) public keys (CA certs). If the default
     bundle file isn't adequate, you can specify an alternate file
     using the --cacert option.
    If this HTTPS server uses a certificate signed by a CA represented in
     the bundle, the certificate verification probably failed due to a
     problem with the certificate (it might be expired, or the name might
     not match the domain name in the URL).
    If you'd like to turn off curl's verification of the certificate, use
     the -k (or --insecure) option.
    
  • Wrong Location & IP

    Wrong Location & IP

    the Website & API recently started to show wrong locations & IP address comparing to other alternatives show my exacte location/ip....

    Any help would be appreciated

  • Heroku deploy problem

    Heroku deploy problem

    While deploying on Heroku I get some errors:

    Counting objects: 1210, done.
    Delta compression using up to 2 threads.
    Compressing objects: 100% (690/690), done.
    Writing objects: 100% (1210/1210), 631.22 KiB, done.
    Total 1210 (delta 472), reused 1022 (delta 467)
    remote: Compressing source files... done.
    remote: Building source:
    remote: 
    remote: -----> Fetching custom git buildpack... done
    remote: -----> Go app detected
    remote: -----> Installing go1.4... done
    remote: -----> Running: godep go install -tags heroku ./...
    remote: cmd/freegeoip/main.go:20:2: cannot find package "github.com/fiorix/go-redis/redis" in any of:
    remote:     /app/tmp/cache/go1.4/go/src/github.com/fiorix/go-redis/redis (from $GOROOT)
    remote:     /tmp/build_302ca8290b15fc58739db8af3cc335ac/.heroku/g/src/github.com/fiorix/freegeoip/Godeps/_workspace/src/github.com/fiorix/go-redis/redis (from $GOPATH)
    remote:     /tmp/build_302ca8290b15fc58739db8af3cc335ac/.heroku/g/src/github.com/fiorix/go-redis/redis
    remote: cmd/freegeoip/main.go:21:2: cannot find package "github.com/gorilla/context" in any of:
    remote:     /app/tmp/cache/go1.4/go/src/github.com/gorilla/context (from $GOROOT)
    remote:     /tmp/build_302ca8290b15fc58739db8af3cc335ac/.heroku/g/src/github.com/fiorix/freegeoip/Godeps/_workspace/src/github.com/gorilla/context (from $GOPATH)
    remote:     /tmp/build_302ca8290b15fc58739db8af3cc335ac/.heroku/g/src/github.com/gorilla/context
    remote: godep: go exit status 1
    remote: 
    remote:  !     Push rejected, failed to compile Go app
    remote: 
    remote: Verifying deploy...
    remote: 
    remote: !   Push rejected to cryptic-temple-9401.
    remote: 
    

    before push to Heroku I did make godep save my Go version: go1.4

  • change broke things

    change broke things

    Hello,

    The change that does the "browser check" breaks code I have deployed to remote systems.

    Can this be rolled back for like 1 hour so I can recover?

    thx

  • Deploying to own server with SSL

    Deploying to own server with SSL

    Hey guys, I'm having trouble deploying to my server with ssl/https. It works fine over http, but when I do 'sudo docker run --net=host --restart=always -d fiorix/freegeoip -cert "something.crt" -key "something.key" -https ":8080"' and try to "curl https://My_URL:8080/json/", it outputs "Unknown SSL protocol error in connection to My_URL:8080" on my laptop, or "curl: (7) Failed to connect to localhost port 8080: Connection refused" on the server itself . I know that my .crt and .key files are correct because nginx is working properly with them on the same server. Any ideas?

  • CloudFlare says freegeoip is under attack

    CloudFlare says freegeoip is under attack

    And now I've got this message on the admin panel:

    CloudFlare has been temporarily deactivated for this site due to a large attack. We do not offer advanced DDOS protection in our Free or Pro plans. All temporary holds are based on a domain, so you cannot delete the website and re-add it. We will automatically resume the CloudFlare service in 5 to 7 business days.

    CloudFlare includes advanced DDOS protection in its Business plan ($200/month). If you upgrade to the Business plan, your website will be re-activated.

  • CORS disabled in 3.1.x

    CORS disabled in 3.1.x

    Hi,

    it seems like CORS has been disbled in version 3.1.0 and upwards.By default I get no CORS headers at all and when trying the binary releases (on linux) the flag -cors-origin doesn't seem to change anything. Is this by design?

    Awesome server btw, fast and so simple to get up and running :clap: Thanks!

  • Installation instructions

    Installation instructions

    For a total newbie in Go are there clear instructions as to how I can deploy this on my Ubuntu server?

    I dont have docker installed in it and I am not planning to go that way either.

    Thanks in advance :heart:

  • Incorrect location for 23.247.211.0/24

    Incorrect location for 23.247.211.0/24

    Incorrect location for 23.247.211.0/24

    This is a local internet service provider.

    Correct Location: Waxahachie, TX USA

    See geofeed at: https://www.fiberfly.com/geofeed.csv

    Company website: https://fiberfly.com/

  • freegeoip.app showing wrong info while maxmind is showing correctly

    freegeoip.app showing wrong info while maxmind is showing correctly

    Hi,

    I just looked up my IP, curl -s https://freegeoip.app/xml/172.58.193.243 172.58.193.243 US United States MI Michigan Detroit 48205 America/Detroit 42.437 -82.99 505

    Detroit, MI is all wrong.. while https://www.maxmind.com/en/locate-my-ip-address is showing the correct information:

    IP Address | Country Code | Location | Network | Postal Code | Approximate Coordinates* | Accuracy Radius (km) | ISP | Organization | Domain | Metro Code -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- 172.58.193.243 | US | Tennessee,United States,North America | 172.58.193.0/24 |   | 36.1671,-86.7861 | 200 | T-Mobile USA | T-Mobile USA

  • freegeoip has a new home

    freegeoip has a new home

    As of this week, freegeoip has a new home at https://github.com/apilayer/freegeoip/

    This repo will be archived soon and if you have inquiries going forward please open issues on that repo instead. The domain freegeoip.net is being transitioned to apilayer's infrastructure and we expect no service disruption, but if you find anything wrong please report to @apilayer.

    I am done with running freegeoip after 9 years of its existence. :)

    cc @packetrich, @gleicon

記帳-PWA-web-app (Bookkeeping-PWA-web-app)
記帳-PWA-web-app (Bookkeeping-PWA-web-app)

GoKeep (bookkeeping web app) 記帳-PWA-web-app (Bookkeeping-PWA-web-app) demo link : https://bookkepping.herokuapp.com/ 測試用帳密 : tester002 , tester002 (亦可

Jan 31, 2022
log4jScanner: provides you with the ability to scan internal (only) subnets for vulnerable log4j web servicelog4jScanner: provides you with the ability to scan internal (only) subnets for vulnerable log4j web service
log4jScanner: provides you with the ability to scan internal (only) subnets for vulnerable log4j web servicelog4jScanner: provides you with the ability to scan internal (only) subnets for vulnerable log4j web service

log4jScanner Goals This tool provides you with the ability to scan internal (only) subnets for vulnerable log4j web services. It will attempt to send

Jan 5, 2023
Web terminal - A (unsafe) technical demo to export a shell to web browser
Web terminal - A (unsafe) technical demo to export a shell to web browser

Web Terminal A (unsafe) technical demo to export a shell to web browser. This pr

Dec 27, 2022
Go-web-scaffold - A simple scaffold for building web app quickly

Go-web-scaffold A simple scaffold for building web app quickly. features This sc

Jan 21, 2022
A quick and easy password protected web server for your files. httpfolder makes downloading/uploading files from your current working directory easy, even for fairly large files.

httpfolder A quick and easy password protected web server for your files. httpfolder makes downloading/uploading files from your current working direc

Sep 12, 2022
A basic example of a go web server with a react frontend
A basic example of a go web server with a react frontend

GO-React starter This is a basic example of a go web server with a react frontend. It uses the go fiber framework Getting started Running locally Clon

Nov 16, 2021
Salmon - A music tracking web server
Salmon - A music tracking web server

Salmon is a music tracking server that connects with different sources to displa

Jan 19, 2022
Polite, slim and concurrent web crawler.

gocrawl gocrawl is a polite, slim and concurrent web crawler written in Go. For a simpler yet more flexible web crawler written in a more idiomatic Go

Dec 31, 2022
sigurlx a web application attack surface mapping tool.

sigurlx a web application attack surface mapping tool, it does ...:

Jul 24, 2021
Minimalist open-source web analytics

Zero-effort web analytics. This is a self-hosted open-source version of Nullitics.

Nov 10, 2022
Generate a modern Web project with Go and Angular, React or Vue in seconds 🚀
Generate a modern Web project with Go and Angular, React or Vue in seconds 🚀

Goxygen Generate a Web project with Go and Angular, React or Vue. Goxygen aims at saving your time while setting up a new project. It creates a skelet

Jan 5, 2023
GoTTY - Share your terminal as a web application
 GoTTY - Share your terminal as a web application

GoTTY - Share your terminal as a web application GoTTY is a simple command line tool that turns your CLI tools into web applications. Installation Fro

Dec 28, 2022
GoCondor is a golang web framework with an MVC like architecture, it's based on Gin framework
GoCondor is a golang web framework with an MVC like architecture, it's based on Gin framework

GoCondor is a golang web framework with an MVC like architecture, it's based on Gin framework, it features a simple organized directory structure for your next project with a pleasant development experience, made for developing modern APIs and microservices.

Dec 29, 2022
OliveTin is a web interface for running Linux shell commands.
OliveTin is a web interface for running Linux shell commands.

OliveTin OliveTin is a web interface for running Linux shell commands. Some example use cases; Give controlled access to run shell commands to less te

Dec 30, 2022
GoatCounter is an open source web analytics platform available as a hosted service or self-hosted app

GoatCounter is an open source web analytics platform available as a hosted service (free for non-commercial use) or self-hosted app. It aims to offer easy to use and meaningful privacy-friendly web analytics as an alternative to Google Analytics or Matomo.

Dec 29, 2022
Short examples of common anti-patterns in Go Web Applications.

Go Web App Anti-Patterns This repository contains short examples of common anti-patterns in Go Web Applications. For complete description, see Common

Dec 31, 2022
📔 Journal helps you manage multiple journals with ease from the comfort of your terminal, web browser or API client.
📔 Journal helps you manage multiple journals with ease from the comfort of your terminal, web browser or API client.

Journal helps you manage multiple journals with ease from the comfort of your terminal, web browser or API client. You can import/export journals as horcruxes and set simple customizations for layout, theme, and keybindings.

Sep 14, 2022
Retro-Floppy UI is a web based application for managing & using a GoTek floppy emulator running the Flash Floppy firmware.
Retro-Floppy UI is a web based application for managing & using a GoTek floppy emulator running the Flash Floppy firmware.

A web user interface for a GoTek running flashfloppy utilising a Raspberry PI 0W as the storage. This allows for remote uploading of files & selecting which disk image is loaded on a retro computer like the BBC Micro or Amiga A1200

Dec 10, 2022
A web application attack surface mapping tool. It takes in a list of urls then performs numerous probes

sigurlscann3r A web application attack surface mapping tool. It takes in a list of urls then performs numerous probes Resources Features Installation

Sep 24, 2022