{"id":13528386,"url":"https://github.com/runk/node-maxmind","last_synced_at":"2026-02-01T23:00:56.135Z","repository":{"id":7346893,"uuid":"8670592","full_name":"runk/node-maxmind","owner":"runk","description":"Maxmind GEO Lookup ","archived":false,"fork":false,"pushed_at":"2026-01-01T14:36:43.000Z","size":19428,"stargazers_count":638,"open_issues_count":1,"forks_count":69,"subscribers_count":15,"default_branch":"master","last_synced_at":"2026-01-06T06:21:44.478Z","etag":null,"topics":["geoip2","hacktoberfest","maxmind","maxmind-binary-databases","mmdb"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/runk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["runk"]}},"created_at":"2013-03-09T14:15:23.000Z","updated_at":"2026-01-04T14:54:06.000Z","dependencies_parsed_at":"2023-09-25T23:18:28.461Z","dependency_job_id":"90fcae8e-ea6d-4221-8e89-545ad98909aa","html_url":"https://github.com/runk/node-maxmind","commit_stats":{"total_commits":965,"total_committers":32,"mean_commits":30.15625,"dds":0.5170984455958549,"last_synced_commit":"1455243a705a476f8fe7958f037581c2ce655456"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/runk/node-maxmind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runk%2Fnode-maxmind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runk%2Fnode-maxmind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runk%2Fnode-maxmind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runk%2Fnode-maxmind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runk","download_url":"https://codeload.github.com/runk/node-maxmind/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runk%2Fnode-maxmind/sbom","scorecard":{"id":789792,"data":{"date":"2025-08-11","repo":{"name":"github.com/runk/node-maxmind","commit":"31e81f9a9f1e9e448b43906e6e5b8be93ccf6a0d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.2,"checks":[{"name":"Code-Review","score":0,"reason":"Found 1/26 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"19 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Warn: no topLevel permission defined: .github/workflows/release.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/runk/node-maxmind/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/runk/node-maxmind/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/runk/node-maxmind/release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/runk/node-maxmind/release.yml/master?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/build.yml:26","Warn: npmCommand not pinned by hash: .github/workflows/release.yml:21","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:7"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T07:11:08.539Z","repository_id":7346893,"created_at":"2025-08-23T07:11:08.539Z","updated_at":"2025-08-23T07:11:08.539Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28993725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T22:01:47.507Z","status":"ssl_error","status_checked_at":"2026-02-01T21:58:37.335Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","hacktoberfest","maxmind","maxmind-binary-databases","mmdb"],"created_at":"2024-08-01T06:02:30.141Z","updated_at":"2026-02-01T23:00:56.109Z","avatar_url":"https://github.com/runk.png","language":"TypeScript","funding_links":["https://github.com/sponsors/runk"],"categories":["TypeScript"],"sub_categories":[],"readme":"# node-maxmind\n\nJavascript module for Geo IP lookup using Maxmind binary databases (aka mmdb or geoip2).\nFastest Maxmind lookup library available - up to [17,000% faster](https://github.com/runk/node-maxmind-benchmark) than other libraries. Module has 100% test coverage with comprehensive test suite. It natively works with binary Maxmind database format and doesn't require any \"CSV - {specific lib format}\" conversions as some other modules do. Maxmind binary databases are highly optimized for size and performance so there's no point using other formats.\n\n## GEO databases\n\nYou might want to use [geolite2](https://github.com/runk/node-geolite2) module with free geo databases. Alternatively, free databases available for [download here](http://dev.maxmind.com/geoip/geoip2/geolite2/). If you need better accuracy you should consider buying [commercial subscription](https://www.maxmind.com/en/geoip2-databases).\n\n## Installation\n\n```shell\nnpm i maxmind\n```\n\n## Usage\n\n```typescript\nimport maxmind, { CityResponse } from 'maxmind';\n\nconst lookup = await maxmind.open\u003cCityResponse\u003e('/path/to/GeoLite2-City.mmdb');\nconsole.log(lookup.get('66.6.44.4')); // inferred type maxmind.CityResponse\n\nconsole.log(lookup.getWithPrefixLength('66.6.44.4')); // tuple with inferred type [maxmind.CityResponse|null, number]\n```\n\n### Sync API\n\nYou can use `Reader` class directly in case if you would want to instantiate it in non-async fashion. Use cases would include receiving a buffer database over network, or just reading it synchronously from disk.\n\n```typescript\nimport { Reader } from 'maxmind';\nconst buffer = fs.readFileSync('./db.mmdb');\nconst lookup = new Reader\u003cCityResponse\u003e(buffer);\nconst city = lookup.get('8.8.8.8');\n\nconst [city2, prefixLength] = lookup.getWithPrefixLength('66.6.44.4');\n```\n\nSupported response types:\n\n```\n- CountryResponse\n- CityResponse\n- AnonymousIPResponse\n- AsnResponse\n- ConnectionTypeResponse\n- DomainResponse\n- IspResponse\n```\n\n## IPv6 Support\n\nModule is fully compatible with IPv6. There are no differences in API between IPv4 and IPv6.\n\n```javascript\nconst lookup = await maxmind.open('/path/to/GeoLite2.mmdb');\nconst location = lookup.get('2001:4860:0:1001::3004:ef68');\n```\n\n## Options\n\n_maxmind.open(filepath, [options])_\n\n- `filepath`: `\u003cstring\u003e` Path to the binary mmdb database file.\n- `options`: `\u003cObject\u003e`\n  - `cache`: `\u003cObject\u003e` Cache options. Under the bonnet module uses [tiny-lru](https://github.com/avoidwork/tiny-lru) cache.\n    - `max`: `\u003cnumber\u003e` Max cache items to keep in memory. _Default_: `10_000`.\n  - `watchForUpdates`: `\u003cboolean\u003e` Supports reloading the reader when changes occur to the database that is loaded. _Default_: `false`.\n  - `watchForUpdatesNonPersistent`: `\u003cboolean\u003e` Controls whether the watcher should be persistent or not. If it is persistent, a node process will be blocked in watching state if the watcher is the only thing still running in the program. _Default_: `false`.\n  - `watchForUpdatesHook`: `\u003cFunction\u003e` Hook function that is fired on database update. _Default_: `null`.\n\n## Does it work in browser?\n\nCurrent module is designed to work in node.js environment. Check out [mmdb-lib](https://github.com/runk/mmdb-lib) that's used under the bonnet - it's environment agnostic and does work in browser.\n\n## IP addresses validation\n\nModule supports validation for both IPv4 and IPv6:\n\n```javascript\nmaxmind.validate('66.6.44.4'); // returns true\nmaxmind.validate('66.6.44.boom!'); // returns false\n\nmaxmind.validate('2001:4860:0:1001::3004:ef68'); // returns true\nmaxmind.validate('2001:4860:0:1001::3004:boom!'); // returns false\n```\n\n## GeoIP Legacy binary format\n\nIn case you want to use legacy GeoIP binary databases you should use [maxmind@0.6](https://github.com/runk/node-maxmind/releases/tag/v0.6.0).\n\n## References\n\n- [MMDB library](https://github.com/runk/mmdb-lib)\n- MaxMind DB file format specification http://maxmind.github.io/MaxMind-DB/\n- MaxMind test/sample DB files https://github.com/maxmind/MaxMind-DB\n- GeoLite2 Free Downloadable Databases http://dev.maxmind.com/geoip/geoip2/geolite2/\n- Great talk about V8 performance https://www.youtube.com/watch?v=UJPdhx5zTaw\n- V8 Optimization killers https://github.com/petkaantonov/bluebird/wiki/Optimization-killers\n- More V8 performance tips http://www.html5rocks.com/en/tutorials/speed/v8/\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunk%2Fnode-maxmind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunk%2Fnode-maxmind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunk%2Fnode-maxmind/lists"}