#geo-ip #geolocation #maxmind #gis

app geoip-api

geoip-api provides geographical information about the specified IP address with an auto-updating database

2 releases

0.7.1 Jun 2, 2020
0.7.0 Jun 1, 2020

#215 in Geospatial

Apache-2.0

28KB
402 lines

geoip-api

If you do not require an auto-updating database or prometheus metrics, you should check out ffissore/geoip-rs, the inspiration for this project.

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

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

    If the provided IP address is invalid, it returns an error

  • 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://localhost:3000/?ip=216.58.205.132&lang=ja

  • Instead of reading from a file, geoip-api will regularly check for updates to the maxminddb online. See the usage below, on how to configure this.

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 (will return an 400 error code):

  AddressNotFoundError: Address not found in database

Speed

I was able to achieve 150k requests per second on my machine.

geoip-api does choose to hold the entire database in memory, rather than writing it to a file. Since it must download the new database while still serving requests from the old one, please allow at least 512 MB of memory for this.

Usage

Install geoip-api with

cargo install geoip-api

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 options via the command-line or environment variables,

USAGE:
    geoip-api [OPTIONS] --account-id <account-id> --license-key <license-key>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --account-id <account-id>             [env: GEOIP_API_ACCOUNT_ID=]
        --edition-id <edition-id>             [env: GEOIP_API_EDITION_ID=]  [default: GeoIP2-City]
        --license-key <license-key>           [env: GEOIP_API_LICENSE_KEY=]
    -l, --listen-addr <listen-addr>           [env: GEOIP_API_LISTEN_ADDR=]  [default: 127.0.0.1:3000]
        --update-minutes <update-minutes>     [env: GEOIP_API_UPDATE_MINUTES=]  [default: 30]

e.g.

 geoip-api =-account-id 123456 --license-key s3cretlicense --update-minutes 30
 # or
 export GEOIP_API_ACCOUNT_ID=123456
 export GEOIP_API_LICENSE_KEY=s3cretlicense
 geoip-api

License

This project is licensed under the Apache License, Version 2.0

Dependencies

~27–40MB
~712K SLoC