README.md

geoip-rs

geoip-rs is a geoip service: it provides geographical information about the calling or the specified IP address. It supports both IPV4 and IPV6.

• When called with no query params, it resolves the calling IP address. For example: https://api.geoip.rs

• When called with the ip query param, it resolves the specified IP address. For example: https://api.geoip.rs/?ip=216.58.205.132

  If the provided IP address is invalid, it falls back to the calling IP address.

• When called with the callback query param, it returns a JSONP response, with the json wrapped by the specified callback. For example: https://api.geoip.rs/?ip=216.58.205.132&callback=my_function

• By default, responses will be in english. An optional lang query param can be provided: if a translation is available, returned data will be in that language. Current list includes: de, en, es, fr, ja, pt-BR, ru, zh-CH. For example: https://api.geoip.rs/?ip=216.58.205.132&lang=ja

Example response

Valid ip address:

{
  "ip_address": "46.51.179.90",
  "latitude": 53.3331,
  "longitude": -6.2489,
  "postal_code": "D02",
  "continent_code": "EU",
  "continent_name": "Europe",
  "country_code": "IE",
  "country_name": "Ireland",
  "region_code": "L",
  "region_name": "Leinster",
  "province_code": "",
  "province_name": "",
  "city_name": "Dublin",
  "timezone": "Europe/Dublin"
}

Not found (private) ip address:

{
  "ip_address": "127.0.0.1"
}

Speed

On an 8 cores Intel i7, geoip.rs can serve ~30K requests/sec.

Dataset

geoip-rs uses the free dataset provided by maxmind. It's not bundled: you have to download it separately.

Download "GeoLite2 City" dataset in binary format from here and unzip it.

Running

Install geoip.rs with

cargo install geoip-rs

If you don't have cargo, install it with

curl https://sh.rustup.rs -sSf | sh

or read the tutorial for additional instructions.

You can specify the dataset location on the command line

geoip-rs /path/to/GeoLite2-City.mmdb

or via environment variable

export GEOIP_RS_DB_PATH=/path/to/GeoLite2-City.mmdb
geoip-rs

or via .env

cp .env.template .env
#edit .env appropriately
geoip-rs

You can also customize the host and port geoip.rs will listen to

export GEOIP_RS_DB_PATH=/path/to/GeoLite2-City.mmdb
export GEOIP_RS_HOST=192.168.0.1
export GEOIP_RS_PORT=8080
geoip-rs

or you can copy .env.template to .env and customize its contents

License

This project is licensed under the Apache License, Version 2.0