"Ido Keido" (緯度経度) in Japanese means "Latitude Longitude" 🌐 🇯🇵
Ido Keido is an open source geolocation service API to determine city, location, country, and continent from given IP addresses, using MaxMind Country and City geolocation binary databases, with support for both IPv4 and IPv6 formats.
Ido Keido was initially created as an internal application at FindHotel. Nowadays it is used as a base application for the same internal geolocation service.
MaxMind provides free and paid versions of geolocation databases:
- GeoLite2 free downloadable databases (less accurate than MaxMind’s GeoIP2 databases): https://dev.maxmind.com/geoip/geoip2/geolite2
- MaxMind’s GeoIP2 databases: City (https://www.maxmind.com/en/geoip2-city) and Country (https://www.maxmind.com/en/geoip2-country-database)
Both binary databases versions are supported by Ido Keido.
Ido Keido was proudly built using Elixir, a dynamic and functional programming language designed for building scalable and maintainable applications.
Each result of a lookup by IP on the databases is cached on ETS (Erlang Term Storage), caching distinctly city and country results by IP. Subsequent requests using the same IP will retrieve the data from cache, avoiding a new lookup on the database.
ETS, a powerful storage engine built into OTP and available to use in Elixir, allows us to store any Elixir term in an in-memory table.
For more details about ETS as a cache see https://elixir-lang.org/getting-started/mix-otp/ets.html#ets-as-a-cache.
Ido Keido application is published as a Docker image in Docker Hub: https://hub.docker.com/r/findhotel/ido_keido
The Ido Keido's Docker image provides a way to run the geolocation service API out of the box.
The geolocation databases are not included in the Docker image. You need to download the MaxMind Country and City geolocation binary databases prior to run the application and rename the database files as following:
- Country database:
country.mmdb - Country database:
city.mmdb
In order to download the databases, you can:
- Download direct from MaxMind website; or
- Clone the Ido Keido's Github repository and run the make command
download-databases, that downloads the databases to[application_root]/datadirectory and renames the database files them properly.
make download-databases
In the "Development" documentation of Ido Keidos's Github repository you find the usage details of download-databases make command
Once the database files as available in your machine, (pull and) run the Docker image setting the
volume parameter (-v) with the local database directory.
docker run -e PORT=4004 -v <full_path_to_databases>:/opt/app/data -p 4004:4004 --rm -it findhotel/ido_keido
Ido Keido API will be available on http:://localhost:4004. For example, retrieving country information: http://localhost:4004/country/2a02:a210:1580:6100:ecf5:e0b7:e7e5:84a1. The complete list of endpoints is described in "API Endpoints" section.
To run IEx (Elixir's Interactive Shell) from the Docker image use the following command:
docker run -e PORT=4004 -v <full_path_to_databases>:/opt/app/data --rm -it findhotel/ido_keido bin/ido_keido console
TODO
http://localhost:4004/country/95.97.71.51
{
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "NL",
"name": "Netherlands"
},
"ip": "95.97.71.51"
}
http://localhost:4004/city/95.97.71.51
{
"city": {
"name": "Amsterdam"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "NL",
"name": "Netherlands"
},
"ip": "95.97.71.51",
"location": {
"accuracy_radius": 5,
"latitude": 52.3551,
"longitude": 4.8788,
"time_zone": "Europe/Amsterdam"
}
}
http://localhost:4004/status
{
"date_time": "2019-03-14T16:04:16.027180Z",
"status": "ok"
}
See the development instructions.
See the contributing guide.
Ido Keido is released under the Apache 2.0 License. See the LICENSE file.
Ido Keido uses GeoLite2 data created by MaxMind, available from https://www.maxmind.com.