{"id":20932511,"url":"https://github.com/adulau/mmdb-server","last_synced_at":"2025-04-06T23:16:11.232Z","repository":{"id":45708997,"uuid":"451140235","full_name":"adulau/mmdb-server","owner":"adulau","description":"mmdb-server is an open source fast API server to lookup IP addresses for their geographic location. ","archived":false,"fork":false,"pushed_at":"2025-03-13T07:30:25.000Z","size":190654,"stargazers_count":156,"open_issues_count":2,"forks_count":21,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T22:09:44.829Z","etag":null,"topics":["geolocation","geolocation-database","ip-geolocation","ip-geolocation-api","mmdb"],"latest_commit_sha":null,"homepage":"https://adulau.github.io/mmdb-server/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adulau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2022-01-23T15:07:19.000Z","updated_at":"2025-03-24T18:32:24.000Z","dependencies_parsed_at":"2022-07-30T12:18:00.717Z","dependency_job_id":"b5a4f7f8-342e-4df3-aab2-694913c8e605","html_url":"https://github.com/adulau/mmdb-server","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adulau%2Fmmdb-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adulau%2Fmmdb-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adulau%2Fmmdb-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adulau%2Fmmdb-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adulau","download_url":"https://codeload.github.com/adulau/mmdb-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563935,"owners_count":20958971,"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":["geolocation","geolocation-database","ip-geolocation","ip-geolocation-api","mmdb"],"created_at":"2024-11-18T21:48:55.410Z","updated_at":"2025-04-06T23:16:11.209Z","avatar_url":"https://github.com/adulau.png","language":"Python","readme":"# mmdb-server\n\nmmdb-server is an open source fast API server to lookup IP addresses for their geographic location, AS number. The server can be used with any [MaxMind DB File Format](https://maxmind.github.io/MaxMind-DB/) or file in the same format.\n\nmmdb-server includes a free and open [GeoOpen-Country database](https://data.public.lu/fr/datasets/geo-open-ip-address-geolocation-per-country-in-mmdb-format/) for IPv4 and IPv6 addresses. The file [GeoOpen-Country](https://cra.circl.lu/opendata/geo-open/mmdb-country/) and [GeoOpen-Country-ASN](https://cra.circl.lu/opendata/geo-open/mmdb-country-asn/) are generated on a regular basis from AS announces and their respective whois records.\n\n# Installation\n\nPython 3.10+ is required to run the mmdb-server with poetry.\n\n- `curl -sSL https://install.python-poetry.org | python3 -`\n- Log out and Log in again\n- `poetry install`\n- `cp ./etc/server.conf.sample ./etc/server.conf`\n- `cd  ./db; bash update.sh; cd ..` (to get the latest version of the GeoOpen database)\n- `poetry run serve`\n\n# Usage\n\n## Lookup of an IP address\n\n`curl -s http://127.0.0.1:8000/geolookup/188.65.220.25 | jq .`\n\n```json\n[\n  {\n    \"country\": {\n      \"iso_code\": \"BE\"\n    },\n    \"meta\": {\n      \"description\": {\n        \"en\": \"Geo Open MMDB database - https://github.com/adulau/mmdb-server\"\n      },\n      \"build_db\": \"2022-02-05 11:37:33\",\n      \"db_source\": \"GeoOpen-Country\",\n      \"nb_nodes\": 1159974\n    },\n    \"ip\": \"188.65.220.25\",\n    \"country_info\": {\n      \"Country\": \"Belgium\",\n      \"Alpha-2 code\": \"BE\",\n      \"Alpha-3 code\": \"BEL\",\n      \"Numeric code\": \"56\",\n      \"Latitude (average)\": \"50.8333\",\n      \"Longitude (average)\": \"4\"\n    }\n  },\n  {\n    \"country\": {\n      \"iso_code\": \"BE\",\n      \"AutonomousSystemNumber\": \"49677\",\n      \"AutonomousSystemOrganization\": \"MAEHDROS-AS\"\n    },\n    \"meta\": {\n      \"description\": {\n        \"en\": \"Geo Open MMDB database - https://github.com/adulau/mmdb-server\"\n      },\n      \"build_db\": \"2022-02-06 10:30:25\",\n      \"db_source\": \"GeoOpen-Country-ASN\",\n      \"nb_nodes\": 1159815\n    },\n    \"ip\": \"188.65.220.25\",\n    \"country_info\": {\n      \"Country\": \"Belgium\",\n      \"Alpha-2 code\": \"BE\",\n      \"Alpha-3 code\": \"BEL\",\n      \"Numeric code\": \"56\",\n      \"Latitude (average)\": \"50.8333\",\n      \"Longitude (average)\": \"4\"\n    }\n  }\n]\n```\n\n`$ curl -s http://127.0.0.1:8000/geolookup/2a02:21d0::68:69:25 | jq .`\n\n```json\n[\n  {\n    \"country\": {\n      \"iso_code\": \"BE\"\n    },\n    \"meta\": {\n      \"description\": {\n        \"en\": \"Geo Open MMDB database - https://github.com/adulau/mmdb-server\"\n      },\n      \"build_db\": \"2022-02-05 11:37:33\",\n      \"db_source\": \"GeoOpen-Country\",\n      \"nb_nodes\": 1159974\n    },\n    \"ip\": \"2a02:21d0::68:69:25\",\n    \"country_info\": {\n      \"Country\": \"Belgium\",\n      \"Alpha-2 code\": \"BE\",\n      \"Alpha-3 code\": \"BEL\",\n      \"Numeric code\": \"56\",\n      \"Latitude (average)\": \"50.8333\",\n      \"Longitude (average)\": \"4\"\n    }\n  },\n  {\n    \"country\": {\n      \"iso_code\": \"BE\",\n      \"AutonomousSystemNumber\": \"49677\",\n      \"AutonomousSystemOrganization\": \"MAEHDROS-AS\"\n    },\n    \"meta\": {\n      \"description\": {\n        \"en\": \"Geo Open MMDB database - https://github.com/adulau/mmdb-server\"\n      },\n      \"build_db\": \"2022-02-06 10:30:25\",\n      \"db_source\": \"GeoOpen-Country-ASN\",\n      \"nb_nodes\": 1159815\n    },\n    \"ip\": \"2a02:21d0::68:69:25\",\n    \"country_info\": {\n      \"Country\": \"Belgium\",\n      \"Alpha-2 code\": \"BE\",\n      \"Alpha-3 code\": \"BEL\",\n      \"Numeric code\": \"56\",\n      \"Latitude (average)\": \"50.8333\",\n      \"Longitude (average)\": \"4\"\n    }\n  }\n]\n```\n\n# Output format\n\nThe output format is an array of JSON object (to support the ability to serve multiple geo location database).  Each JSON object of the JSON array includes a `meta`, `country`, `ip` and `country_info` fields. The `country` give the geographic location of the IP address queried. The `meta` field includes the origin of the MMDB database which the the metadata. `ip` returns the queried IP address. `country_info` gives additional information about the country such as `Country`, `Alpha-2 code`, `Alpha-3 code`, `Numeric code`, Latitude and Longitude (average centric value).\n\n# Public online version of mmdb-server\n\n- [https://ip.circl.lu/](https://ip.circl.lu/) - lookup via [https://ip.circl.lu/geolookup/8.8.8.8](https://ip.circl.lu/geolookup/8.8.8.8)\n- [https://ipv4.circl.lu](https://ipv4.circl.lu/) If you are dual-homed IPv6/IPv4, return your IPv4 address. \n- [https://ipv6.circl.lu](https://ipv6.circl.lu/) If you are dual-homed IPv6/IPv4, return your IPv6 address. \n\n# License\n\n```\n    Copyright (C) 2022-2024 Alexandre Dulaunoy\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU Affero General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU Affero General Public License for more details.\n\n    You should have received a copy of the GNU Affero General Public License\n    along with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadulau%2Fmmdb-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadulau%2Fmmdb-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadulau%2Fmmdb-server/lists"}