{"id":20324850,"url":"https://github.com/viodotcom/ido_keido","last_synced_at":"2025-04-11T19:42:20.476Z","repository":{"id":66942150,"uuid":"175384784","full_name":"viodotcom/ido_keido","owner":"viodotcom","description":"Ido Keido is a geolocation service API to determine city, location, country, and continent from given IP addresses. [Maintainers: @prodis @zekus]","archived":false,"fork":false,"pushed_at":"2019-03-25T09:54:20.000Z","size":90,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T15:49:08.943Z","etag":null,"topics":["docker","elixir","findhotel","geolocation","geolocation-api","idokeido","phoenix"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viodotcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-13T09:08:15.000Z","updated_at":"2024-08-16T06:36:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"0376b6e7-c3e8-4e6e-8070-0f3499950538","html_url":"https://github.com/viodotcom/ido_keido","commit_stats":null,"previous_names":["viodotcom/ido_keido"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viodotcom%2Fido_keido","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viodotcom%2Fido_keido/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viodotcom%2Fido_keido/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viodotcom%2Fido_keido/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viodotcom","download_url":"https://codeload.github.com/viodotcom/ido_keido/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248468521,"owners_count":21108834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","elixir","findhotel","geolocation","geolocation-api","idokeido","phoenix"],"created_at":"2024-11-14T19:37:53.888Z","updated_at":"2025-04-11T19:42:20.448Z","avatar_url":"https://github.com/viodotcom.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Ido Keido](https://github.com/FindHotel/ido_keido/blob/master/docs/ido_keido_logo.png)\n\n# Ido Keido\n\n\"Ido Keido\" (緯度経度) in Japanese means \"Latitude Longitude\" 🌐 🇯🇵\n\nIdo Keido is an open source geolocation service API to determine city, location, country, and\ncontinent from given IP addresses, using [MaxMind](https://www.maxmind.com) Country and City\ngeolocation binary databases, with support for both IPv4 and IPv6 formats.\n\nIdo Keido was initially created as an internal application at [FindHotel](http://company.findhotel.net).\nNowadays it is used as a base application for the same internal geolocation service.\n\nMaxMind provides free and paid versions of geolocation databases:\n- GeoLite2 free downloadable databases (less accurate than MaxMind’s GeoIP2 databases): https://dev.maxmind.com/geoip/geoip2/geolite2\n- MaxMind’s GeoIP2 databases: City (https://www.maxmind.com/en/geoip2-city) and Country (https://www.maxmind.com/en/geoip2-country-database)\n\nBoth binary databases versions are supported by Ido Keido.\n\n## Technologies\n\n### Elixir\n\n![Elixir](https://camo.githubusercontent.com/9c090491439e7054b157aeaf27a709c7679105cf/68747470733a2f2f656c697869722d6c616e672e6f72672f696d616765732f6c6f676f2f6c6f676f2e706e67)\n\nIdo Keido was proudly built using [Elixir](https://elixir-lang.org), a dynamic and functional\nprogramming language designed for building scalable and maintainable applications.\n\n### Cache with ETS\n\n![Erlang](https://camo.githubusercontent.com/6d67ad5ca0b8874af6c47201378129fbe1b0c503/687474703a2f2f7777772e65726c616e672e6f72672f696d672f65726c616e672e706e67)\n\nEach result of a lookup by IP on the databases is cached on [ETS (Erlang Term Storage)](http://erlang.org/doc/man/ets.html),\ncaching distinctly city and country results by IP. Subsequent requests using the same IP will\nretrieve the data from cache, avoiding a new lookup on the database.\n\nETS, a powerful storage engine built into OTP and available to use in Elixir, allows us to store\nany Elixir term in an in-memory table.\n\nFor more details about ETS as a cache see https://elixir-lang.org/getting-started/mix-otp/ets.html#ets-as-a-cache.\n\n### Docker\n\n![Docker](https://camo.githubusercontent.com/0736f7d8a1c6dd57b9bf46eca5cb3ba70bd3fe5c/68747470733a2f2f75706c6f61642e77696b696d656469612e6f72672f77696b6970656469612f636f6d6d6f6e732f7468756d622f342f34652f446f636b65725f253238636f6e7461696e65725f656e67696e652532395f6c6f676f2e7376672f33303070782d446f636b65725f253238636f6e7461696e65725f656e67696e652532395f6c6f676f2e7376672e706e67)\n\nIdo Keido application is published as a Docker image in Docker Hub: https://hub.docker.com/r/findhotel/ido_keido\n\n\n## Usage\n\nThe Ido Keido's Docker image provides a way to run the geolocation service API out of the box.\n\nThe geolocation databases are not included in the Docker image. You need to download the MaxMind\nCountry and City geolocation binary databases prior to run the application and rename the database\nfiles as following:\n- Country database: `country.mmdb`\n- Country database: `city.mmdb`\n\nIn order to download the databases, you can:\n- Download direct from [MaxMind website](https://dev.maxmind.com/geoip/geoip2/geolite2); or\n- Clone the [Ido Keido's Github repository](https://github.com/FindHotel/ido_keido) and run the make command `download-databases`, that downloads the databases to `[application_root]/data` directory and renames the database files them properly.\n```\nmake download-databases\n```\n\nIn the \"Development\" documentation of Ido Keidos's Github repository you find [the usage details of `download-databases` make command](https://github.com/FindHotel/ido_keido/blob/master/docs/development.md)\n\nOnce the database files as available in your machine, (pull and) run the Docker image setting the\nvolume parameter (`-v`) with the local database directory.\n\n```\ndocker run -e PORT=4004 -v \u003cfull_path_to_databases\u003e:/opt/app/data  -p 4004:4004 --rm -it findhotel/ido_keido\n```\n\nIdo 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](http://localhost:4004/country/2a02:a210:1580:6100:ecf5:e0b7:e7e5:84a1). The complete list of endpoints is described in \"API Endpoints\" section. \n\nTo run IEx (Elixir's Interactive Shell) from the Docker image use the following command:\n```\ndocker run -e PORT=4004 -v \u003cfull_path_to_databases\u003e:/opt/app/data --rm -it findhotel/ido_keido bin/ido_keido console\n```\n\n### Extending for your own application\n\nTODO\n\n\n## API Endpoints\n\n### GET /country/:ip\n```\nhttp://localhost:4004/country/95.97.71.51\n\n{\n  \"continent\": {\n    \"code\": \"EU\",\n    \"name\": \"Europe\"\n  },\n  \"country\": {\n    \"code\": \"NL\",\n    \"name\": \"Netherlands\"\n  },\n  \"ip\": \"95.97.71.51\"\n}\n```\n\n### GET /city/:ip\n```\nhttp://localhost:4004/city/95.97.71.51\n\n{\n  \"city\": {\n    \"name\": \"Amsterdam\"\n  },\n  \"continent\": {\n    \"code\": \"EU\",\n    \"name\": \"Europe\"\n  },\n  \"country\": {\n    \"code\": \"NL\",\n    \"name\": \"Netherlands\"\n  },\n  \"ip\": \"95.97.71.51\",\n  \"location\": {\n    \"accuracy_radius\": 5,\n    \"latitude\": 52.3551,\n    \"longitude\": 4.8788,\n    \"time_zone\": \"Europe/Amsterdam\"\n  }\n}\n```\n\n### GET /status\n```\nhttp://localhost:4004/status\n\n{\n  \"date_time\": \"2019-03-14T16:04:16.027180Z\",\n  \"status\": \"ok\"\n}\n```\n\n## Development\n\nSee the [development instructions](https://github.com/FindHotel/ido_keido/blob/master/docs/development.md).\n\n\n## Contributing\n\nSee the [contributing guide](https://github.com/FindHotel/ido_keido/blob/master/CONTRIBUTING.md).\n\n## License\n\nIdo Keido is released under the Apache 2.0 License. See the [LICENSE](https://github.com/FindHotel/ido_keido/blob/master/LICENSE) file.\n\nIdo Keido uses GeoLite2 data created by MaxMind, available from https://www.maxmind.com.\n\n## Maintainers\n\n- [FindHotel](https://github.com/FindHotel)\n- [Antonio Lorusso (zekus)](https://github.com/zekus)\n- [Fernando Hamasaki de Amorim (prodis)](https://github.com/prodis)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviodotcom%2Fido_keido","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviodotcom%2Fido_keido","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviodotcom%2Fido_keido/lists"}