{"id":16301664,"url":"https://github.com/bbkr/geoip2","last_synced_at":"2025-10-25T13:31:35.486Z","repository":{"id":138947574,"uuid":"133712470","full_name":"bbkr/GeoIP2","owner":"bbkr","description":"MaxMind GeoIP v2 libraries reader for Raku language.","archived":false,"fork":false,"pushed_at":"2024-12-29T01:48:13.000Z","size":125,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-31T07:22:02.518Z","etag":null,"topics":["geoip2","maxmind","raku"],"latest_commit_sha":null,"homepage":"","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbkr.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":"2018-05-16T19:14:38.000Z","updated_at":"2024-12-29T01:48:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"46854862-6fd3-447f-ba3d-7302c527a1fa","html_url":"https://github.com/bbkr/GeoIP2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbkr%2FGeoIP2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbkr%2FGeoIP2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbkr%2FGeoIP2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbkr%2FGeoIP2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbkr","download_url":"https://codeload.github.com/bbkr/GeoIP2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238147631,"owners_count":19424299,"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":["geoip2","maxmind","raku"],"created_at":"2024-10-10T20:55:17.517Z","updated_at":"2025-10-25T13:31:30.142Z","avatar_url":"https://github.com/bbkr.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaxMind GeoIP v2 libraries reader for [Raku](https://www.raku.org) language\n\n[![.github/workflows/test.yml](https://github.com/bbkr/GeoIP2/actions/workflows/test.yml/badge.svg)](https://github.com/bbkr/GeoIP2/actions/workflows/test.yml)\n\nReader for [MaxMind databases](https://www.maxmind.com/en/geoip2-databases) including:\n* Country\n* City\n* Anonymous IP\n* ISP\n* Domain\n* Connection Type\n* in any distribution form ( Lite, Pro, Enterprise )\n* and any other database in [*.mmdb 2.0 format](https://github.com/maxmind/MaxMind-DB/blob/master/MaxMind-DB-spec.md)\n\n## SYNOPSIS\n\n```raku\n    use GeoIP2;\n    \n    my $geo = GeoIP2.new( path =\u003e '/home/me/Database.mmdb' );\n    \n    # lookup by IPv4\n    say $geo.locate( ip =\u003e '8.8.8.8' );\n    \n    # lookup by IPv6\n    say $geo.locate( ip =\u003e '2001:4860:4860:0:0:0:0:8888' );\n    \n    # show database information\n    say $geo.build-timestamp;\n    say $geo.ip-version;\n    say $geo.languages;\n    say $geo.description;\n```\n\n## METHODS\n\n### new( path =\u003e '/home/me/Database.mmdb' )\n\nInitialize database.\n\n### locate( ip =\u003e '1.1.1.1' )\n\nReturn location data for given IP or `Nil` if IP is not found.\n\nIP can be given as:\n* IPv4 dotted decimal format - `8.8.8.8`\n* IPv6 full format - `2001:4860:4860:0000:0000:0000:0000:8888`\n* IPv6 without leading zeroes - `2001:4860:4860:0:0:0:0:8888`\n* (IPv6 compressed format - `2001:4860:4860::8888` - is not yet supported)\n\nNote that returned data structure is specific for opened databse type,\nfor example ISP database returns:\n\n```raku\nGeoIP2.new( path =\u003e './GeoIP2-ISP.mmdb' ).locate( ip =\u003e '78.31.153.58' );\n\n{\n    'autonomous_system_number' =\u003e 29314,\n    'autonomous_system_organization' =\u003e 'Vectra S.A.',\n    'isp' =\u003e 'Jarsat Sp. z o.o.',\n    'organization' =\u003e 'Jarsat Sp. z o.o.'\n}\n```\n\nSometimes returned values are localized, like in City database:\n\n```raku\nGeoIP2.new( path =\u003e './GeoIP2-City.mmdb' ).locate( ip =\u003e '78.31.153.58' );\n\n{\n    'country' =\u003e {\n        'geoname_id' =\u003e 798544,\n        'names' =\u003e {\n            'ru' =\u003e 'Польша',\n            'es' =\u003e 'Polonia',\n            'pt-BR' =\u003e 'Polônia',\n            'zh-CN' =\u003e '波兰',\n            'ja' =\u003e 'ポーランド共和国',\n            'de' =\u003e 'Polen',\n            'fr' =\u003e 'Pologne',\n            'en' =\u003e 'Poland'\n        },\n        'iso_code' =\u003e 'PL',\n        'is_in_european_union' =\u003e True\n    },\n    'city' =\u003e {\n        'geoname_id' =\u003e 3099434,\n        'names' =\u003e {\n            'ru' =\u003e 'Гданьск',\n            'es' =\u003e 'Gdansk',\n            'pt-BR' =\u003e 'Gdańsk',\n            'zh-CN' =\u003e '格但斯克',\n            'ja' =\u003e 'グダニスク',\n            'de' =\u003e 'Danzig',\n            'fr' =\u003e 'Gdańsk',\n            'en' =\u003e 'Gdańsk'\n        }\n    },\n    'continent' =\u003e {\n        'geoname_id' =\u003e 6255148,\n        'names' =\u003e {\n            'ru' =\u003e 'Европа',\n            'es' =\u003e 'Europa',\n            'pt-BR' =\u003e 'Europa',\n            'zh-CN' =\u003e '欧洲',\n            'ja' =\u003e 'ヨーロッパ',\n            'de' =\u003e 'Europa',\n            'fr' =\u003e 'Europe',\n            'en' =\u003e 'Europe'\n        },\n    }\n    'subdivisions' =\u003e [\n        {\n            'geoname_id' =\u003e 3337496,\n            'iso_code' =\u003e 'PM',\n            'names' =\u003e {\n                'de' =\u003e 'Woiwodschaft Pommern',\n                'en' =\u003e 'Pomerania',\n                'es' =\u003e 'Pomerania',\n                'fr' =\u003e 'Voïvodie de Poméranie',\n                'ja' =\u003e 'ポモージェ県',\n                'ru' =\u003e 'Поморское воеводство'\n            }\n        }\n    ],\n    ...\n}\n```\n\nIn such case list of available languages can be also checked through [languages](#languages) attribute.\nIf your language is not provided out-of-the-box please check [TRANSLATIONS](#translations) section.\n\n## ATTRIBUTES\n\n### build-timestamp\n\nDateTime object representing time when database was compiled.\n\n### ip-version\n\nVersion object representing largest supported IP type, for example `v6`.\n\n### languages\n\nSet object representing languages that location names are translated to.\nCheck [TRANSLATIONS](#translations) section if language that you need is not on the list.\n\n### description / description( 'RU' )\n\nString describing database kind, for example `GeoIP2 ISP database`.\nDefault is English but it may be requested in any of the [supported languages](#languages).\n\n### binary-format-version / database-type / ipv4-start-node / node-byte-size / node-count / record-size / search-tree-size\n\nGeeky stuff.\n\n## FLAGS\n\n### debug\n\nHelpful for investigating IP loation and data decoding issues.\nCan be passed in constructor or turned `True` / `False` at any time:\n\n```raku\nmy $geo = GeoIP2.new( path =\u003e '/home/me/Database.mmdb', :debug );\n...\n$geo.debug = False;\n...\n$geo.debug = True;\n...\n```\n\n## REQUIREMENTS\n\nThis is Pure Raku module - maxminddb C library is **not** required.\nHere is how to start with free GeoIP Lite libraries right away:\n\n### MacOS\n\n* Install [HomeBrew](https://brew.sh).\n\nIn terminal:\n\n* Install tool to fetch databases - `brew install geoipupdate`.\n* Fetch databases - `geoipupdate` (may take a while).\n\nIn code:\n\n```raku\nmy $geo = GeoIP2.new( path =\u003e '/usr/local/var/GeoIP/GeoLite2-City.mmdb' );\nsay $geo.locate( ip =\u003e '8.8.8.8' );\n```\n\n### Ubuntu Linux and derivatives\n\nIn terminal:\n\n* Install tool to fetch databases - `sudo apt-get install geoipupdate`.\n* Fetch databases - `sudo geoipupdate` (may take a while).\n\nIn code:\n\n```raku\nmy $geo = GeoIP2.new( path =\u003e '/var/lib/GeoIP/GeoLite2-City.mmdb' );\nsay $geo.locate( ip =\u003e '8.8.8.8' );\n```\n\n### Arch Linux and derivatives\n\nIn terminal:\n\n* Install prepackaged databases - `pacman -Syu geoip2-database`.\n\nIn code:\n\n```raku\nmy $geo = GeoIP2.new( path =\u003e '/usr/share/GeoIP/GeoLite2-City.mmdb' );\nsay $geo.locate( ip =\u003e '8.8.8.8' );\n```\n\nNote that `geoipupdate` tool method is also possible,\nbut because Arch is a rolling release distro installing prepackaged databases\nprovides the same frequency of database updates as fetching direcltly from MaxMind.\n\n## TRANSLATIONS\n\nSome databases have built-in translations, however set of supported languages is rather limited.\nAdditional translations can be obtained from [GeoNames.org](https://geonames.org) by using `geoname_id` column from results.\n\nThe easiest way to do that is to download [this file](http://download.geonames.org/export/dump/alternateNamesV2.zip).\nInside ZIP archive there is tab-separated `alternateNamesV2.txt` file, where:\n\n* second column is `geoname_id`\n* third column may contain 2 or 3 letter lowercased ISO-639 language code\n* fourth column contains traslation\n* fifth column contains 1 if name is official, otherwise it is empty\n\nSo if you need for example Hungarian translation for country from example above you can extract it:\n\n```\n$ cat alternateNamesV2.txt | awk -F \"\\t\" '{ if ( $2 == 798544 \u0026\u0026 $3 == \"hu\" ) print $4 }'\nLengyelország\n```\n\nSometimes there are few translations in the same language:\n\n```\n$ cat alternateNamesV2.txt | awk -F \"\\t\" '{ if ( $2 == 798544 \u0026\u0026 $3 == \"en\" ) print $4 }'\nPoland\nRepublic of Poland\n```\n\nUsually one of them will be marked as \"official\" (fifth column),\nso you can treat such translation with higher priority.\n\n### Native names\n\nUnfortunately there is no indicator which translation is native for which `geoname_id`.\nFirst you have to check which langauge is used in given country and then find translation in that language.\n\nBut beware, there are some countries with more than one official language so you may get more than one native name.\nIt is up to you to decide how to handle such cases.\n\n### Caching ideas\n\nFor fast access you may want to preload those translations into some fast database, for example Redis.\nLet's say you need Swedish translations (language code is `SV`).\n\nFeed unofficial names first (fifth column empty):\n```\ncat alternateNamesV2.txt | awk -F \"\\t\" '{ if ( $3 == \"sv\" \u0026\u0026 $5 == \"\" ) print \"HSET \" $2 \" \" $3 \" \\\"\" $4 \"\\\"\"}' | redis-cli\n```\n\nThen feed known, official names (fifth column is `1`):\n```\ncat alternateNamesV2.txt | awk -F \"\\t\" '{ if ( $3 == \"sv\" \u0026\u0026 $5 == 1 ) print \"HSET \" $2 \" \" $3 \" \\\"\" $4 \"\\\"\"}' | redis-cli\n```\nSometimes official name will overwrite unofficial name.\n\nAnd to find translation of `geoname_id` in Swedish language you simply have to query Redis:\n```\n\u003e HGET 798544 sv\n\"Polen\"\n```\n\nYou can feed more languages into the same database if you need.\n\n## COPYRIGHTS\n\nThis third party reader is released under Artistic-2.0 license\nand is based on [open source database spec](https://github.com/maxmind/MaxMind-DB) released under Creative Commons license.\nWhich means you can use it to read GeoIP2 free and paid databases both for personal and commercial use.\n\nHowever keep in mind that MaxMind® and GeoIP® [are trademarks](https://www.maxmind.com/en/terms_of_use)\nso if you want to fork this module do it [under your own authority](https://docs.perl6.org/language/typesystem#Versioning_and_authorship)\nto avoid confusion with their official libraries.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbkr%2Fgeoip2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbkr%2Fgeoip2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbkr%2Fgeoip2/lists"}