Geolix
MaxMind GeoIP2 database reader/decoder.
Installation
Fetch both the Geolix repository and a distribution of the MaxMind GeoIP2 databases (or the free GeoLite2 variant).
Setup
Dependency
To use Geolix with your projects, edit your mix.exs
file and add the project
as a dependency:
defp deps do
[ { :geolix, "~> 0.1" } ]
end
You should also update your applications to include all necessary projects:
def application do
[ applications: [ :geolix ] ]
end
Configuration
Add the paths of the MaxMind databases you want to use to your project configuration:
use Mix.Config
config :geolix,
databases: [
{ :city, "/path/to/cities/db" },
{ :country, "/path/to/countries/db" }
]
An appropriate filename will be automatically appended to the path.
It is also possible to (re-) configure the loaded databases during runtime:
iex(1)> Geolix.set_database(:city, "/path/to/cities/db.mmdb")
:ok
iex(2)> Geolix.set_database(:country, "/path/to/countries/db.mmdb")
:ok
If Geolix cannot find the database it will return { :error, message }
,
otherwise the return value will be :ok
.
Usage
Geolix can be used via convenience GenServer calls:
iex(1)> Geolix.lookup("127.0.0.1")
%{ city: %Geolix.Result.City{ ... },
country: %Geolix.Result.Country{ ... }}
iex(2)> Geolix.lookup({ 127, 0, 0, 1 }, [ as: :raw, where: :city ])
%{ ... }
Note: Only IPv4 lookups using downloaded database files are possible at the moment.
Using Geolix.lookup/2
with only one parameter (the IP) will lookup the
information on all registered databases, returning nil
if the IP was not
found.
Lookup options:
:as
- Return the result as a:struct
or:raw
(plain map):where
- Lookup information in a single registered database
Every non-nil result will include the IP as a tuple either directly in the
result field :ip_address
or inside %{ traits: %{ ip_address: ... }}
if
a city or country database is used.
Benchmarking
If you are curious on how long a lookup of an IP takes, you can simply measure it using the erlang :timer module:
iex(1)> :timer.tc(fn -> Geolix.lookup({ 108, 168, 255, 243 }) end)
{ 1337,
%{ city: ... ,
country: ... } }
The time returned are the microseconds
of the complete lookup including
every overhead by for example the process pool. For more details refer to the
official erlang documentation.
Result Verification
For (ongoing) verification of the result accuracy a special test environment is configured for each travis run.
This environment performs the following 4 steps:
- generate a set of random IPs
- lookup using geolix
- lookup using python (geoip2)
- compare the results
To run these tests on a local machine please refer to the travis scripts
executed on each run
(i.e. ./travis/verify_install.sh
and ./travis/verify_script.sh
).
License
License information about the supported MaxMind GeoIP2 Country, MaxMind GeoIP2 City and MaxMind GeoLite2 databases can be found on their respective sites.