{"id":17549170,"url":"https://github.com/yhirose/maxminddb","last_synced_at":"2025-05-15T17:02:25.298Z","repository":{"id":13916021,"uuid":"16615171","full_name":"yhirose/maxminddb","owner":"yhirose","description":"Pure Ruby GeoIP2 MaxMind DB reader.","archived":false,"fork":false,"pushed_at":"2021-11-19T15:21:00.000Z","size":104,"stargazers_count":297,"open_issues_count":3,"forks_count":56,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-31T21:45:43.301Z","etag":null,"topics":["ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yhirose.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-07T13:22:17.000Z","updated_at":"2024-12-30T16:11:38.000Z","dependencies_parsed_at":"2022-07-26T18:00:09.122Z","dependency_job_id":null,"html_url":"https://github.com/yhirose/maxminddb","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhirose%2Fmaxminddb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhirose%2Fmaxminddb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhirose%2Fmaxminddb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhirose%2Fmaxminddb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yhirose","download_url":"https://codeload.github.com/yhirose/maxminddb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737769,"owners_count":20987718,"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":["ruby","ruby-gem"],"created_at":"2024-10-21T02:50:02.686Z","updated_at":"2025-04-07T22:07:07.270Z","avatar_url":"https://github.com/yhirose.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# maxminddb\n\nPure Ruby [GeoIP2 MaxMind DB](http://maxmind.github.io/MaxMind-DB/) reader, which doesn't require [libmaxminddb](https://github.com/maxmind/libmaxminddb).\n\nYou can find more information about the GeoIP2 database [here](http://dev.maxmind.com/geoip/geoip2/downloadable/).\n\n[![Gem Version](https://badge.fury.io/rb/maxminddb.svg)](http://badge.fury.io/rb/maxminddb)\n[![Build Status](https://travis-ci.org/yhirose/maxminddb.svg?branch=master)](https://travis-ci.org/yhirose/maxminddb)\n[![Code Climate](https://codeclimate.com/github/yhirose/maxminddb.svg)](https://codeclimate.com/github/yhirose/maxminddb)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'maxminddb'\n```\n\nAnd then execute:\n\n```sh\n$ bundle\n```\n\nOr install it yourself as:\n\n```sh\n$ gem install maxminddb\n```\n\n## Usage\n\n```ruby\ndb = MaxMindDB.new('./GeoLite2-City.mmdb')\nret = db.lookup('74.125.225.224')\n\nret.found? # =\u003e true\nret.country.name # =\u003e 'United States'\nret.country.name('zh-CN') # =\u003e '美国'\nret.country.iso_code # =\u003e 'US'\nret.city.name(:fr) # =\u003e 'Mountain View'\nret.subdivisions.most_specific.name # =\u003e 'California'\nret.location.latitude # =\u003e -122.0574\nret.to_hash # =\u003e {\"city\"=\u003e{\"geoname_id\"=\u003e5375480, \"names\"=\u003e{\"de\"=\u003e\"Mountain View\", \"en\"=\u003e\"Mountain View\", \"fr\"=\u003e\"Mountain View\", \"ja\"=\u003e\"マウンテンビュー\", \"ru\"=\u003e\"Маунтин-Вью\", \"zh-CN\"=\u003e\"芒廷维尤\"}}, \"continent\"=\u003e{\"code\"=\u003e\"NA\", \"geoname_id\"=\u003e6255149, \"names\"=\u003e{\"de\"=\u003e\"Nordamerika\", \"en\"=\u003e\"North America\", \"es\"=\u003e\"Norteamérica\", \"fr\"=\u003e\"Amérique du Nord\", \"ja\"=\u003e\"北アメリカ\", \"pt-BR\"=\u003e\"América do Norte\", \"ru\"=\u003e\"Северная Америка\", \"zh-CN\"=\u003e\"北美洲\"}}, \"country\"=\u003e{\"geoname_id\"=\u003e6252001, \"iso_code\"=\u003e\"US\", \"names\"=\u003e{\"de\"=\u003e\"USA\", \"en\"=\u003e\"United States\", \"es\"=\u003e\"Estados Unidos\", \"fr\"=\u003e\"États-Unis\", \"ja\"=\u003e\"アメリカ合衆国\", \"pt-BR\"=\u003e\"Estados Unidos\", \"ru\"=\u003e\"Сша\", \"zh-CN\"=\u003e\"美国\"}}, \"location\"=\u003e{\"latitude\"=\u003e37.419200000000004, \"longitude\"=\u003e-122.0574, \"metro_code\"=\u003e807, \"time_zone\"=\u003e\"America/Los_Angeles\"}, \"postal\"=\u003e{\"code\"=\u003e\"94043\"}, \"registered_country\"=\u003e{\"geoname_id\"=\u003e6252001, \"iso_code\"=\u003e\"US\", \"names\"=\u003e{\"de\"=\u003e\"USA\", \"en\"=\u003e\"United States\", \"es\"=\u003e\"Estados Unidos\", \"fr\"=\u003e\"États-Unis\", \"ja\"=\u003e\"アメリカ合衆国\", \"pt-BR\"=\u003e\"Estados Unidos\", \"ru\"=\u003e\"Сша\", \"zh-CN\"=\u003e\"美国\"}}, \"subdivisions\"=\u003e[{\"geoname_id\"=\u003e5332921, \"iso_code\"=\u003e\"CA\", \"names\"=\u003e{\"de\"=\u003e\"Kalifornien\", \"en\"=\u003e\"California\", \"es\"=\u003e\"California\", \"fr\"=\u003e\"Californie\", \"ja\"=\u003e\"カリフォルニア州\", \"pt-BR\"=\u003e\"Califórnia\", \"ru\"=\u003e\"Калифорния\", \"zh-CN\"=\u003e\"加利福尼亚州\"}}]}\n```\n\nEven if no result could be found, you can ask for the attributes without guarding for nil:\n\n```ruby\ndb = MaxMindDB.new('./GeoLite2-City.mmdb')\nret = db.lookup('127.0.0.1')\nret.found? # =\u003e false\nret.country.name # =\u003e nil\nret.to_hash # =\u003e {}\n```\n\nFor testing or other purposes, you might wish to treat localhost IP addresses as some other address - an external one. You can do this by assigning the desired external IP address to the attribute local_ip_alias:\n\n```ruby\ndb = MaxMindDB.new('./GeoLite2-City.mmdb')\nret = db.local_ip_alias = '74.125.225.224'\nret = db.lookup('127.0.0.1')\nret.found? # =\u003e true\nret.country.name # =\u003e 'United States'\nret.to_hash.empty? # =\u003e false\n```\n\nIt's also possible to access the database metadata.\n\n```ruby\ndb = MaxMindDB.new('./GeoLite2-City.mmdb')\ndb.metadata['build_epoch'] # =\u003e 1493762948\ndb.metadata # =\u003e {\"binary_format_major_version\"=\u003e2, \"binary_format_minor_version\"=\u003e0, \"build_epoch\"=\u003e1493762948, \"database_type\"=\u003e\"GeoLite2-City\", \"description\"=\u003e{\"en\"=\u003e\"GeoLite2 City database\"}, \"ip_version\"=\u003e6, \"languages\"=\u003e[\"de\", \"en\", \"es\", \"fr\", \"ja\", \"pt-BR\", \"ru\", \"zh-CN\"], \"node_count\"=\u003e3678850, \"record_size\"=\u003e28}\n```\n\n### Regarding thread safety\n\nA MaxMindDB instance doesn't do any write operation after it is created. So we can consider it as an immutable object which is 'thread-safe'.\n\n### File reading strategies\n\nBy default, `MaxMinDB.new` will read the entire database into memory. This makes subsequent lookups fast, but can result in a fairly large memory overhead.\n\nIf having a low memory overhead is important, you can use the `LowMemoryReader` by passing a `file_reader` argument to `MaxMindDB.new`. For example:\n\n```ruby\ndb = MaxMindDB.new('./GeoLite2-City.mmdb', MaxMindDB::LOW_MEMORY_FILE_READER)\nret = db.lookup('74.125.225.224')\n```\n\nThe `LowMemoryReader` will not load the entire database into memory. It's important to note that for Ruby versions lower than `2.5.0`, the `LowMemoryReader` is not process safe. Forking a process after initializing a `MaxMindDB` instance can lead to unexpected results. For Ruby versions \u003e= `2.5.0`, `LowMemoryReader` uses `File.pread` which works safely in forking environments.\n\n## Contributing\n\n1.  Fork it ( http://github.com/yhirose/maxminddb/fork )\n2.  Create your feature branch (`git checkout -b my-new-feature`)\n3.  Commit your changes (`git commit -am 'Add some feature'`)\n4.  Push to the branch (`git push origin my-new-feature`)\n5.  Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhirose%2Fmaxminddb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyhirose%2Fmaxminddb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhirose%2Fmaxminddb/lists"}