{"id":13677225,"url":"https://github.com/oschwald/maxminddb-golang","last_synced_at":"2026-04-26T22:02:53.644Z","repository":{"id":14190449,"uuid":"16896900","full_name":"oschwald/maxminddb-golang","owner":"oschwald","description":"MaxMind DB Reader for Go","archived":false,"fork":false,"pushed_at":"2026-04-26T17:27:31.000Z","size":833,"stargazers_count":711,"open_issues_count":4,"forks_count":104,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-04-26T19:17:56.163Z","etag":null,"topics":["geoip","geoip2","geolocation","go","ip-address","maxmind","maxmind-db"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oschwald.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-02-16T23:35:39.000Z","updated_at":"2026-04-25T20:09:59.000Z","dependencies_parsed_at":"2023-12-14T01:36:27.038Z","dependency_job_id":"22922034-bbbc-488a-a54c-f53c8de05552","html_url":"https://github.com/oschwald/maxminddb-golang","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/oschwald/maxminddb-golang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oschwald","download_url":"https://codeload.github.com/oschwald/maxminddb-golang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-golang/sbom","scorecard":{"id":713335,"data":{"date":"2025-08-11","repo":{"name":"github.com/oschwald/maxminddb-golang","commit":"58181cd1ec8fa2e374bd845ad1212b014c5e816c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":6.4,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"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":"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":"Code-Review","score":0,"reason":"Found 0/9 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":"30 commit(s) and 2 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":"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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/go.yml:1","Warn: no topLevel permission defined: .github/workflows/golangci-lint.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":3,"reason":"dependency not pinned by hash detected -- score normalized to 3","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:53: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/golangci-lint.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/golangci-lint.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/golangci-lint.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/oschwald/maxminddb-golang/golangci-lint.yml/main?enable=pin","Info:   0 out of   7 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   1 out of   1 goCommand 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":"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":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: ISC 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":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: GoBuiltInFuzzer integration found: fuzz_test.go:17","Info: GoBuiltInFuzzer integration found: fuzz_test.go:53","Info: GoBuiltInFuzzer integration found: fuzz_test.go:103","Info: GoBuiltInFuzzer integration found: fuzz_test.go:214","Info: GoBuiltInFuzzer integration found: fuzz_test.go:253"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"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":"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":"SAST","score":10,"reason":"SAST tool is run on all commits","details":["Info: SAST configuration detected: CodeQL","Info: all commits (23) 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-22T08:45:58.880Z","repository_id":14190449,"created_at":"2025-08-22T08:45:58.880Z","updated_at":"2025-08-22T08:45:58.880Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32314117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"last_error":"SSL_read: 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":["geoip","geoip2","geolocation","go","ip-address","maxmind","maxmind-db"],"created_at":"2024-08-02T13:00:39.113Z","updated_at":"2026-04-26T22:02:53.638Z","avatar_url":"https://github.com/oschwald.png","language":"Go","funding_links":[],"categories":["SQL Builders"],"sub_categories":[],"readme":"# MaxMind DB Reader for Go\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/oschwald/maxminddb-golang/v2.svg)](https://pkg.go.dev/github.com/oschwald/maxminddb-golang/v2)\n\nThis is a Go reader for the MaxMind DB format. Although this can be used to\nread [GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data)\nand [GeoIP2](https://www.maxmind.com/en/geoip2-databases) databases,\n[geoip2](https://github.com/oschwald/geoip2-golang) provides a higher-level API\nfor doing so.\n\nThis is not an official MaxMind API.\n\n## Installation\n\n```bash\ngo get github.com/oschwald/maxminddb-golang/v2\n```\n\n## Version 2.0 Features\n\nVersion 2.0 includes significant improvements:\n\n- **Modern API**: Uses `netip.Addr` instead of `net.IP` for better performance\n- **Custom Unmarshaling**: Implement `Unmarshaler` interface for\n  zero-allocation decoding\n- **Network Iteration**: Iterate over all networks in a database with\n  `Networks()` and `NetworksWithin()`\n- **Enhanced Performance**: Optimized data structures and decoding paths\n- **Go 1.24+ Support**: Takes advantage of modern Go features including\n  iterators\n- **Better Error Handling**: More detailed error types and improved debugging\n- **Integrity Checks**: Validate databases with `Reader.Verify()` and access\n  metadata helpers such as `Metadata.BuildTime()`\n\nSee [MIGRATION.md](MIGRATION.md) for guidance on updating existing v1 code.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"net/netip\"\n\n\t\"github.com/oschwald/maxminddb-golang/v2\"\n)\n\nfunc main() {\n\tdb, err := maxminddb.Open(\"GeoLite2-City.mmdb\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer db.Close()\n\n\tip, err := netip.ParseAddr(\"81.2.69.142\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tvar record struct {\n\t\tCountry struct {\n\t\t\tISOCode string            `maxminddb:\"iso_code\"`\n\t\t\tNames   map[string]string `maxminddb:\"names\"`\n\t\t} `maxminddb:\"country\"`\n\t\tCity struct {\n\t\t\tNames map[string]string `maxminddb:\"names\"`\n\t\t} `maxminddb:\"city\"`\n\t}\n\n\terr = db.Lookup(ip).Decode(\u0026record)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"Country: %s (%s)\\n\", record.Country.Names[\"en\"], record.Country.ISOCode)\n\tfmt.Printf(\"City: %s\\n\", record.City.Names[\"en\"])\n}\n```\n\n## Usage Patterns\n\n### Basic Lookup\n\n```go\ndb, err := maxminddb.Open(\"GeoLite2-City.mmdb\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer db.Close()\n\nvar record any\nip := netip.MustParseAddr(\"1.2.3.4\")\nerr = db.Lookup(ip).Decode(\u0026record)\n```\n\n### Custom Struct Decoding\n\n```go\ntype City struct {\n\tCountry struct {\n\t\tISOCode string `maxminddb:\"iso_code\"`\n\t\tNames   struct {\n\t\t\tEnglish string `maxminddb:\"en\"`\n\t\t\tGerman  string `maxminddb:\"de\"`\n\t\t} `maxminddb:\"names\"`\n\t} `maxminddb:\"country\"`\n}\n\nvar city City\nerr = db.Lookup(ip).Decode(\u0026city)\n```\n\n### High-Performance Custom Unmarshaling\n\n```go\ntype FastCity struct {\n\tCountryISO string\n\tCityName   string\n}\n\nfunc (c *FastCity) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {\n\tmapIter, size, err := d.ReadMap()\n\tif err != nil {\n\t\treturn err\n\t}\n\t// Pre-allocate with correct capacity for better performance\n\t_ = size // Use for pre-allocation if storing map data\n\tfor key, err := range mapIter {\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tswitch string(key) {\n\t\tcase \"country\":\n\t\t\tcountryIter, _, err := d.ReadMap()\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tfor countryKey, countryErr := range countryIter {\n\t\t\t\tif countryErr != nil {\n\t\t\t\t\treturn countryErr\n\t\t\t\t}\n\t\t\t\tif string(countryKey) == \"iso_code\" {\n\t\t\t\t\tc.CountryISO, err = d.ReadString()\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tif err := d.SkipValue(); err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\tdefault:\n\t\t\tif err := d.SkipValue(); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\treturn nil\n}\n```\n\n### Network Iteration\n\n```go\n// Iterate over all networks in the database\nfor result := range db.Networks() {\n\tvar record struct {\n\t\tCountry struct {\n\t\t\tISOCode string `maxminddb:\"iso_code\"`\n\t\t} `maxminddb:\"country\"`\n\t}\n\terr := result.Decode(\u0026record)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Printf(\"%s: %s\\n\", result.Prefix(), record.Country.ISOCode)\n}\n\n// Iterate over networks within a specific prefix\nprefix := netip.MustParsePrefix(\"192.168.0.0/16\")\nfor result := range db.NetworksWithin(prefix) {\n\t// Process networks within 192.168.0.0/16\n}\n```\n\n### Path-Based Decoding\n\n```go\nvar countryCode string\nerr = db.Lookup(ip).DecodePath(\u0026countryCode, \"country\", \"iso_code\")\n\nvar cityName string\nerr = db.Lookup(ip).DecodePath(\u0026cityName, \"city\", \"names\", \"en\")\n```\n\n## Supported Database Types\n\nThis library supports **all MaxMind DB (.mmdb) format databases**, including:\n\n**MaxMind Official Databases:**\n\n- **GeoLite/GeoIP City**: Comprehensive location data including city, country,\n  subdivisions\n- **GeoLite/GeoIP Country**: Country-level geolocation data\n- **GeoLite ASN**: Autonomous System Number and organization data\n- **GeoIP Anonymous IP**: Anonymous network and proxy detection\n- **GeoIP Enterprise**: Enhanced City data with additional business fields\n- **GeoIP ISP**: Internet service provider information\n- **GeoIP Domain**: Second-level domain data\n- **GeoIP Connection Type**: Connection type identification\n\n**Third-Party Databases:**\n\n- **DB-IP databases**: Compatible with DB-IP's .mmdb format databases\n- **IPinfo databases**: Works with IPinfo's MaxMind DB format files\n- **Custom databases**: Any database following the MaxMind DB file format\n  specification\n\nThe library is format-agnostic and will work with any valid .mmdb file\nregardless of the data provider.\n\n## Performance Tips\n\n1. **Reuse Reader instances**: The `Reader` is thread-safe and should be reused\n   across goroutines\n2. **Use specific structs**: Only decode the fields you need rather than using\n   `any`\n3. **Implement Unmarshaler**: For high-throughput applications, implement\n   custom unmarshaling\n4. **Consider caching**: Use `Result.Offset()` as a cache key for database\n   records\n\n## Getting Database Files\n\n### Free GeoLite2 Databases\n\nDownload from\n[MaxMind's GeoLite page](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).\n\n## Documentation\n\n- [Go Reference](https://pkg.go.dev/github.com/oschwald/maxminddb-golang/v2)\n- [MaxMind DB File Format Specification](https://maxmind.github.io/MaxMind-DB/)\n\n## Requirements\n\n- Go 1.24 or later\n- MaxMind DB file in .mmdb format\n\n## Contributing\n\nContributions welcome! Please fork the repository and open a pull request with\nyour changes.\n\n## License\n\nThis is free software, licensed under the ISC License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foschwald%2Fmaxminddb-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foschwald%2Fmaxminddb-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foschwald%2Fmaxminddb-golang/lists"}