/nginx-geoip-api

Minimal GeoIP API based on Nginx and GeoIP2

Primary LanguageDockerfileMIT LicenseMIT

GeoIP2 API

A very simple API built with NGINX + GeoIP2 module to provide geolocation information based on an IP

Features

  • Language agnostic with minimal dependencies (Nginx & GeoIP2 module)
  • Support for these databases
    • GeoIP2-City
    • GeoIP2-Country
    • GeoLite2-ASN
    • GeoIP2-City
    • GeoLite2-Country
  • What info can you get (Check #Examples)?

How to start your own Geo-API

Method 1: Only using the docker image

docker run --rm -d -p 80:80 \
	-e NGINX_GEOIP2_COUNTRY_DB_ENABLED="1" \
	-e NGINX_GEOIP2_CITY_DB_ENABLED="1" \
	-e NGINX_GEOIP2_ASN_DB_ENABLED="1" \
	-v ./maxmind:/usr/share/maxmind:ro \
	declare/nginx-geoip-api

Examples:

  • Check the status of the database: curl http://127.0.0.1/_status
{
   "country_build": 1607405176,
   "city_build": 1607445787,
   "asn_build": 1607445787
}
  • Check information for a given ip: curl -H 'X-Forwarded-For: 37.223.5.39' http://127.0.0.1

You MUST add the X-Forwarded-For header with the client real IP, otherwise it will return the information of the direct client.

{
    "country": "Spain",
    "countryCode": "ES",
    "stateprov": "",
    "stateprovCode": "",
    "city": "Barcelona",
    "latitude": "41.38700",
    "longitude": "2.17010",
    "continent": "EU",
    "timezone": "Europe/Madrid",
    "asn": "12430",
    "asnOrganization": "Vodafone Spain"
}
  • Querying by HTTP header
curl -sI -H "X-Forwarded-For: $(curl -s https://ifconfig.me/ip)" "http://127.0.0.1"
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 03 Apr 2023 05:16:19 GMT
Content-Type: application/octet-stream
Content-Length: 228
Connection: keep-alive
X-GeoIP2-Country: Spain
X-GeoIP2-CountryCode: ES
X-GeoIP2-City: Barcelona
X-GeoIP2-Latitude: 41.38700
X-GeoIP2-Longitude: 2.17010
X-GeoIP2-Continent: EU
X-GeoIP2-Timezone: Europe/Madrid
X-GeoIP2-Asn: 12430
X-GeoIP2-AsnOrganization: Vodafone Spain