mmdb-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 or file in the same format.
mmdb-server includes a free and open GeoOpen-Country database for IPv4 and IPv6 addresses. The file GeoOpen-Country and GeoOpen-Country-ASN are generated on a regular basis from AS announces and their respective whois records.
Python 3.10+ is required to run the mmdb-server with poetry.
curl -sSL https://install.python-poetry.org | python3 -- Log out and Log in again
poetry installcp ./etc/server.conf.sample ./etc/server.confcd ./db; bash update.sh; cd ..(to get the latest version of the GeoOpen database)poetry run serve
docker build -t mmdb-server:latest .docker run -d -p 8000:8000 --name mmdb-server mmdb-server:latest
curl -s http://127.0.0.1:8000/geolookup/188.65.220.25 | jq .
[
{
"country": {
"iso_code": "BE"
},
"meta": {
"description": {
"en": "Geo Open MMDB database - https://github.com/adulau/mmdb-server"
},
"build_db": "2022年02月05日 11:37:33",
"db_source": "GeoOpen-Country",
"nb_nodes": 1159974
},
"ip": "188.65.220.25",
"country_info": {
"Country": "Belgium",
"Alpha-2 code": "BE",
"Alpha-3 code": "BEL",
"Numeric code": "56",
"Latitude (average)": "50.8333",
"Longitude (average)": "4"
}
},
{
"country": {
"iso_code": "BE",
"AutonomousSystemNumber": "49677",
"AutonomousSystemOrganization": "MAEHDROS-AS"
},
"meta": {
"description": {
"en": "Geo Open MMDB database - https://github.com/adulau/mmdb-server"
},
"build_db": "2022年02月06日 10:30:25",
"db_source": "GeoOpen-Country-ASN",
"nb_nodes": 1159815
},
"ip": "188.65.220.25",
"country_info": {
"Country": "Belgium",
"Alpha-2 code": "BE",
"Alpha-3 code": "BEL",
"Numeric code": "56",
"Latitude (average)": "50.8333",
"Longitude (average)": "4"
}
}
]$ curl -s http://127.0.0.1:8000/geolookup/2a02:21d0::68:69:25 | jq .
[
{
"country": {
"iso_code": "BE"
},
"meta": {
"description": {
"en": "Geo Open MMDB database - https://github.com/adulau/mmdb-server"
},
"build_db": "2022年02月05日 11:37:33",
"db_source": "GeoOpen-Country",
"nb_nodes": 1159974
},
"ip": "2a02:21d0::68:69:25",
"country_info": {
"Country": "Belgium",
"Alpha-2 code": "BE",
"Alpha-3 code": "BEL",
"Numeric code": "56",
"Latitude (average)": "50.8333",
"Longitude (average)": "4"
}
},
{
"country": {
"iso_code": "BE",
"AutonomousSystemNumber": "49677",
"AutonomousSystemOrganization": "MAEHDROS-AS"
},
"meta": {
"description": {
"en": "Geo Open MMDB database - https://github.com/adulau/mmdb-server"
},
"build_db": "2022年02月06日 10:30:25",
"db_source": "GeoOpen-Country-ASN",
"nb_nodes": 1159815
},
"ip": "2a02:21d0::68:69:25",
"country_info": {
"Country": "Belgium",
"Alpha-2 code": "BE",
"Alpha-3 code": "BEL",
"Numeric code": "56",
"Latitude (average)": "50.8333",
"Longitude (average)": "4"
}
}
]The 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).
- https://ip.circl.lu/ - lookup via https://ip.circl.lu/geolookup/8.8.8.8
- https://ipv4.circl.lu If you are dual-homed IPv6/IPv4, return your IPv4 address.
- https://ipv6.circl.lu If you are dual-homed IPv6/IPv4, return your IPv6 address.
Copyright (C) 2022-2025 Alexandre Dulaunoy
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.