{"id":13514353,"url":"https://github.com/fiorix/freegeoip","last_synced_at":"2025-05-14T12:12:23.490Z","repository":{"id":1065734,"uuid":"902930","full_name":"fiorix/freegeoip","owner":"fiorix","description":"IP geolocation web server","archived":false,"fork":false,"pushed_at":"2022-08-27T01:14:26.000Z","size":4288,"stargazers_count":4938,"open_issues_count":5,"forks_count":791,"subscribers_count":198,"default_branch":"master","last_synced_at":"2025-04-11T05:00:09.497Z","etag":null,"topics":["freegeoip","geolocation","go","ip-database"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fiorix.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-09-11T03:56:27.000Z","updated_at":"2025-04-08T20:41:33.000Z","dependencies_parsed_at":"2022-07-20T12:17:21.363Z","dependency_job_id":null,"html_url":"https://github.com/fiorix/freegeoip","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiorix%2Ffreegeoip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiorix%2Ffreegeoip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiorix%2Ffreegeoip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiorix%2Ffreegeoip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fiorix","download_url":"https://codeload.github.com/fiorix/freegeoip/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140768,"owners_count":22021220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freegeoip","geolocation","go","ip-database"],"created_at":"2024-08-01T05:00:54.144Z","updated_at":"2025-05-14T12:12:18.321Z","avatar_url":"https://github.com/fiorix.png","language":"Go","funding_links":[],"categories":["Go","go","Repositories"],"sub_categories":[],"readme":"# freegeoip\n\n**NOTE:** as of April 2018 this repository is no longer active. Please visit https://github.com/apilayer/freegeoip/ for the current version.\n\n---\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)\n\nThis is the source code of the freegeoip software. It contains both the web server that empowers freegeoip.net, and a package for the [Go](http://golang.org) programming language that enables any web server to support IP geolocation with a simple and clean API.\n\nSee http://en.wikipedia.org/wiki/Geolocation for details about geolocation.\n\nDevelopers looking for the Go API can skip to the [Package freegeoip](#packagefreegeoip) section below.\n\n## Running\n\nThis 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.\n\n### Docker\n\n#### Install Docker\n\nDocker has [install instructions for many platforms](https://docs.docker.com/engine/installation/),\nincluding\n- [Ubuntu](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/)\n- [CentOS](https://docs.docker.com/engine/installation/linux/docker-ce/centos/)\n- [Mac](https://docs.docker.com/docker-for-mac/install/)\n\n#### Run the API in a container\n\n```bash\ndocker run --restart=always -p 8080:8080 -d fiorix/freegeoip\n```\n\n#### Test\n\n```bash\ncurl localhost:8080/json/1.2.3.4\n# =\u003e {\"ip\":\"1.2.3.4\",\"country_code\":\"US\",\"country_name\":\"United States\", # ...\n```\n\n### Other Linux, OS X, FreeBSD, and Windows\n\nThere are [pre-compiled binaries](https://github.com/fiorix/freegeoip/releases) available.\n\n### Production configuration\n\nFor production workloads you may want to use different configuration for the freegeoip web server, for example:\n\n* Enabling the \"internal server\" for collecting metrics and profiling/tracing the freegeoip web server on demand\n* Monitoring the internal server using [Prometheus](https://prometheus.io), or exporting your metrics to [New Relic](https://newrelic.com)\n* Serving the freegeoip API over HTTPS (TLS) using your own certificates, or provisioned automatically using [LetsEncrypt.org](https://letsencrypt.org)\n* Configuring [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) to restrict your browser clients to always use HTTPS\n* Configuring the read and write timeouts to avoid stale clients consuming server resources\n* 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\n* Configuring [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) to restrict access to your API to specific domains\n* 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\n* Optimizing your round trips by enabling [TCP Fast Open](https://en.wikipedia.org/wiki/TCP_Fast_Open) on your OS and the freegeoip web server\n* 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\n* Serve the default [GeoLite2 City](http://dev.maxmind.com/geoip/geoip2/geolite2/) free database that is downloaded and updated automatically in background on a configurable schedule, or\n* Serve the commercial [GeoIP2 City](https://www.maxmind.com/en/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\n\nSee the [Server Options](#serveroptions) section below for more information on configuring the server.\n\nFor automation, check out the [freegeoip chef cookbook](https://supermarket.chef.io/cookbooks/freegeoip) or the (legacy) [Ansible Playbook](./cmd/freegeoip/ansible-playbook) for Ubuntu 14.04 LTS.\n\n\u003ca name=\"serveroptions\"\u003e\n\n### Server Options\n\nTo see all the available options, use the `-help` option:\n\n```bash\ndocker run --rm -it fiorix/freegeoip -help\n```\n\nIf 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):\n\n```bash\ndocker run -p 8888:8888 -p 80:8080 -p 443:8443 -d fiorix/freegeoip \\\n\t-internal-server=:8888 \\\n\t-http=:8080 \\\n\t-https=:8443 \\\n\t-hsts=max-age=31536000 \\\n\t-letsencrypt \\\n\t-letsencrypt-hosts=myfancydomain.io\n```\n\n 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:\n\n```bash\n$ cat prod.env\nFREEGEOIP_INTERNAL_SERVER=:8888\nFREEGEOIP_HTTP=:8080\nFREEGEOIP_HTTPS=:8443\nFREEGEOIP_HSTS=max-age=31536000\nFREEGEOIP_LETSENCRYPT=true\nFREEGEOIP_LETSENCRYPT_HOSTS=myfancydomain.io\n\n$ docker run --env-file=prod.env -p 8888:8888 -p 80:8080 -p 443:8443 -d fiorix/freegeoip\n```\n\nBy default, HTTP/2 is enabled over HTTPS. You can disable by passing the `-http2=false` flag.\n\nAlso, 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.\n\nIf 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`.\n\n## Database\n\nThe current implementation uses the free [GeoLite2 City](http://dev.maxmind.com/geoip/geoip2/geolite2/) database from MaxMind.\n\nIn 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.\n\nIf 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.\n\nIn 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.\n\nAll responses from the freegeiop API contain the date that the database was downloaded in the X-Database-Date HTTP header.\n\n## API\n\nThe freegeoip API is served by endpoints that encode the response in different formats.\n\nExample:\n\n```bash\ncurl freegeoip.net/json/\n```\n\nReturns the geolocation information of your own IP address, the source IP address of the connection.\n\nYou 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:\n\n```bash\ncurl freegeoip.net/json/github.com\n```\n\nSame semantics are available for the `/xml/{ip}` and `/csv/{ip}` endpoints.\n\nJSON responses can be encoded as JSONP, by adding the `callback` parameter:\n\n```bash\ncurl freegeoip.net/json/?callback=foobar\n```\n\nThe callback parameter is ignored on all other endpoints.\n\n## Metrics and profiling\n\nThe freegeoip web server can provide metrics about its usage, and also supports runtime profiling and tracing.\n\nBoth are disabled by default, but can be enabled by passing the `-internal-server` parameter in the command line. Metrics are generated for [Prometheus](http://prometheus.io) and can be queried at `/metrics` even with curl.\n\nHTTP pprof is available at `/debug/pprof` and the examples from the [pprof](https://golang.org/pkg/net/http/pprof/) package documentation should work on the freegeiop web server.\n\n\u003ca name=\"packagefreegeoip\"\u003e\n\n## Package freegeoip\n\nThe freegeoip package for the Go programming language provides two APIs:\n\n- A database API that requires zero maintenance of the IP database;\n- A geolocation `http.Handler` that can be used/served by any http server.\n\ntl;dr if all you want is code then see the `example_test.go` file.\n\nOtherwise check out the godoc reference.\n\n[![GoDoc](https://godoc.org/github.com/fiorix/freegeoip?status.svg)](https://godoc.org/github.com/fiorix/freegeoip)\n[![Build Status](https://secure.travis-ci.org/fiorix/freegeoip.png)](http://travis-ci.org/fiorix/freegeoip)\n[![GoReportCard](https://goreportcard.com/badge/github.com/fiorix/freegeoip)](https://goreportcard.com/report/github.com/fiorix/freegeoip)\n\n### Features\n\n- Zero maintenance\n\nThe 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.\n\n- DevOps friendly\n\nIf 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.\n\n- Extensible\n\nBesides 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.\n\n### Install\n\nDownload the package:\n\n\tgo get -d github.com/fiorix/freegeoip/...\n\nInstall the web server:\n\n\tgo install github.com/fiorix/freegeoip/cmd/freegeoip\n\nTest coverage is quite good, and test code may help you find the stuff you need.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiorix%2Ffreegeoip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffiorix%2Ffreegeoip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiorix%2Ffreegeoip/lists"}