{"id":13583589,"url":"https://github.com/ipfs-shipyard/ipfs-geoip","last_synced_at":"2025-09-02T15:04:07.841Z","repository":{"id":31350050,"uuid":"34912847","full_name":"ipfs-shipyard/ipfs-geoip","owner":"ipfs-shipyard","description":"geoip lookup over DAG-CBOR dataset loaded from IPFS","archived":false,"fork":false,"pushed_at":"2025-03-28T13:09:29.000Z","size":3494,"stargazers_count":72,"open_issues_count":7,"forks_count":21,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-08-31T18:58:44.350Z","etag":null,"topics":["b-tree","dag","dag-cbor","geoip","ipfs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ipfs-geoip","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"OpenBEL/language","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs-shipyard.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-05-01T16:48:47.000Z","updated_at":"2025-03-28T13:07:55.000Z","dependencies_parsed_at":"2023-11-28T04:29:23.015Z","dependency_job_id":"7a205352-20ba-42d9-b802-91672172a2ae","html_url":"https://github.com/ipfs-shipyard/ipfs-geoip","commit_stats":{"total_commits":98,"total_committers":18,"mean_commits":5.444444444444445,"dds":0.653061224489796,"last_synced_commit":"bf605b6364480e8c8188c52fb934d9ef7ccc8ab2"},"previous_names":["krl/ipfs-geoip"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/ipfs-shipyard/ipfs-geoip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-shipyard%2Fipfs-geoip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-shipyard%2Fipfs-geoip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-shipyard%2Fipfs-geoip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-shipyard%2Fipfs-geoip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs-shipyard","download_url":"https://codeload.github.com/ipfs-shipyard/ipfs-geoip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-shipyard%2Fipfs-geoip/sbom","scorecard":{"id":493683,"data":{"date":"2025-08-11","repo":{"name":"github.com/ipfs-shipyard/ipfs-geoip","commit":"855c1b7cc2aacfc60f470cb21f4f19c4d9d9c0ab"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.8,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","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":"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":"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":"Code-Review","score":2,"reason":"Found 7/29 approved changesets -- score normalized to 2","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":"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":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/generated-pr.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/ipfs-shipyard/ipfs-geoip/generated-pr.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/js-test-and-release.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/ipfs-shipyard/ipfs-geoip/js-test-and-release.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/stale.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/ipfs-shipyard/ipfs-geoip/stale.yml/main?enable=pin","Info:   0 out of   3 third-party GitHubAction 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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: topLevel 'packages' permission set to 'write': .github/workflows/js-test-and-release.yml:13","Warn: topLevel 'contents' permission set to 'write': .github/workflows/js-test-and-release.yml:11","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":"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":"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":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"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":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 15 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"}},{"name":"Vulnerabilities","score":1,"reason":"9 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-67mh-4wv8-2f99","Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp","Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55","Warn: Project is vulnerable to: GHSA-hcrg-fc28-fcg5","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-cxrh-j4jr-qwg3"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T19:53:05.775Z","repository_id":31350050,"created_at":"2025-08-19T19:53:05.775Z","updated_at":"2025-08-19T19:53:05.775Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273301876,"owners_count":25081105,"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","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["b-tree","dag","dag-cbor","geoip","ipfs"],"created_at":"2024-08-01T15:03:36.664Z","updated_at":"2025-09-02T15:04:07.816Z","avatar_url":"https://github.com/ipfs-shipyard.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# IPFS GeoIP\n\n[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)\n[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)\n[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)\n[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n[![Dependency Status](https://david-dm.org/ipfs/ipfs-geoip.svg?style=flat-square)](https://david-dm.org/ipfs/ipfs-geoip)\n[![Travis CI](https://img.shields.io/travis/ipfs-shipyard/ipfs-geoip/master.svg?style=flat-square)](https://travis-ci.org/ipfs-shipyard/ipfs-geoip)\n[![](https://data.jsdelivr.com/v1/package/npm/ipfs-geoip/badge)](https://www.jsdelivr.com/package/npm/ipfs-geoip)\n[![Coverage Status](https://coveralls.io/repos/github/ipfs/ipfs-geoip/badge.svg?branch=master)](https://coveralls.io/github/ipfs/ipfs-geoip?branch=master)\n\n\u003e GeoIP lookup over IPFS\n\n\n# Table of Contents\n\n- [IPFS GeoIP](#ipfs-geoip)\n- [Table of Contents](#table-of-contents)\n  - [Install](#install)\n    - [NPM](#npm)\n    - [CDN](#cdn)\n  - [Usage](#usage)\n  - [API](#api)\n    - [`lookup(ipfs, ip)`](#lookupipfs-ip)\n    - [`lookupPretty(ipfs, multiaddrs)`](#lookupprettyipfs-multiaddrs)\n  - [Maintenance](#maintenance)\n    - [CIDs of the lookup dataset](#cids-of-the-lookup-dataset)\n    - [Updating GeoLite2 dataset](#updating-geolite2-dataset)\n  - [Testing in CLI](#testing-in-cli)\n  - [Contribute](#contribute)\n    - [Want to hack on IPFS?](#want-to-hack-on-ipfs)\n  - [License](#license)\n\n## Install\n\n### NPM\n\n\n```js\nnpm install --save ipfs-geoip\n```\n\n### CDN\n\nInstead of a local installation (and browserification) you may request a specific\nversion `N.N.N` as a [remote copy from jsDelivr](https://www.jsdelivr.com/package/npm/ipfs-geoip):\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { lookup } from 'https://cdn.jsdelivr.net/npm/ipfs-geoip@N.N.N/dist/index.min.js';\n  const gateway = 'https://ipfs.io'\n  console.log(await lookup(gateway, '66.6.44.4'))\n\u003c/script\u003e\n```\n\nThe response in the console should look similar to:\n```js\n{\n    \"country_name\": \"USA\",\n    \"country_code\": \"US\",\n    \"region_code\": \"VA\",\n    \"city\": \"Ashburn\",\n    \"postal_code\": \"20149\",\n    \"latitude\": 39.0469,\n    \"longitude\": -77.4903,\n    \"planet\": \"Earth\"\n}\n```\n\n## Usage\n\n### With public gateways (default)\n\nIf `gateways` is a string or array of strings with public gateway URLs, it will be used for\nfetching IPFS blocks as [`application/vnd.ipld.raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw)\nand parsing them as DAG-CBOR locally via [@ipld/dag-cbor](https://www.npmjs.com/package/@ipld/dag-cbor):\n\n```js\nconst geoip = require('ipfs-geoip')\nconst exampleIp = '66.6.44.4'\n\nconst gateways = ['https://ipfs.io', 'https://dweb.link']\n\ntry {\n  const result = await geoip.lookup(gateways, exampleIp)\n  console.log('Result: ', result)\n} catch (err) {\n  console.log('Error: ' + err)\n}\n\ntry {\n  const result = await geoip.lookupPretty(gateways, '/ip4/' + exampleIp)\n  console.log('Pretty result: %s', result.formatted)\n} catch (err) {\n  console.log('Error: ' + err)\n}\n```\n\n### With custom block getter function\n\nIt is also possible to use it with local or remote IPFS node by passing block getter function, e.g., one that exposes\n[`ipfs.block.get` Core JS API](https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/BLOCK.md#ipfsblockgetcid-options):\n\n```js\nconst geoip = require('ipfs-geoip')\nconst exampleIp = '66.6.44.4'\n\nconst ipfs = require('ipfs-http-client')()\n\ntry {\n  const getBlock = (cid) =\u003e ipfs.block.get(cid)\n  const result = await geoip.lookup(getBlock, exampleIp)\n  console.log('Result: ', result)\n} catch (err) {\n  console.log('Error: ' + err)\n}\n```\n\n## API\n\n### `lookup(ipfs, ip)`\n\nReturns a promise that resolves to an object of the form\n\n```js\n{\n  \"country_code\": \"US\",\n  \"country_name\": \"USA\",\n  \"region_code\": \"CA\",\n  \"city\": \"Mountain View\",\n  \"postal_code\": \"94040\",\n  \"latitude\": 37.3860,\n  \"longitude\": -122.0838,\n  \"planet\": \"Earth\"\n}\n```\n\n### `lookupPretty(ipfs, multiaddrs)`\n\nProvides the same results as `lookup` with the addition of\na `formatted` property that looks like this: `Mountain View, CA, United States, Earth`.\n\n## Maintenance\n\n### CIDs of the lookup dataset\n\nThe current root hash for lookups is defined under `GEOIP_ROOT` in `src/lookup.js`.\n\nIt is a proprietary b-tree generated from source files provided defined under `DATA_HASH` in `src/generate/index.js`.\n\n### Updating GeoLite2 dataset\n\nThere is a generator included, that can be run with\n\n```bash\n$ npm run generate\n```\n\nThis takes quite a long time to import, but you only need to do it once when updating the global index used by the lookup feature.\n\nIt reads original GeoLite CSV files provided from `DATA_HASH` directory defined\nin `src/generate/index.js`, and turns them into a 32-way branching b-tree\nof [DAG-CBOR](https://ipld.io/specs/codecs/dag-cbor/spec/) objects.\n\nThe tree is saved as `ipfs-geoip.car` and the root CID is printed to the\nterminal. It should then be imported to IPFS and the root CID should be pinned\nin multiple locations,  and stored as the new `GEOIP_ROOT` in `src/lookup.js`\n\n\u003e 👉 this library uses [`dag-cbor`](https://ipld.io/specs/codecs/dag-cbor/spec/)\n\u003e and reads raw blocks via [`ipfs.block` RPC](https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/BLOCK.md),\n\u003e but could be refactored to fetch blocks as [`application/vnd.ipld.raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw)\n\u003e from a regular [HTTP Gateway](https://docs.ipfs.tech/reference/http/gateway/).\n\n\n## Testing in CLI\n\nIt is possible to run tests against a local gateway by passing `IPFS_GATEWAY`:\n\n```console\n$ IPFS_GATEWAY=\"http://127.0.0.1:8080\" npm test\n```\n\nYou can find an example of how to use this in [`example/lookup.js`](example/lookup.js), which you can use like this:\n\n```bash\n$ export IPFS_GATEWAY=\"http://127.0.0.1:8080\"\n$ node example/lookup.js 66.6.44.4\nResult: {\n  \"country_name\": \"USA\",\n  \"country_code\": \"US\",\n  \"region_code\": \"NY\",\n  \"city\": \"New York\",\n  \"postal_code\": \"10004\",\n  \"latitude\": 40.7126,\n  \"longitude\": -74.0066,\n  \"planet\": \"Earth\"\n}\nPretty result: New York, NY, USA, Earth\n```\n\n\n## Contribute\n\nFeel free to join in. All welcome. Open an [issue](https://github.com/ipfs/ipfs-geoip/issues)!\n\nThis repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).\n\n### Want to hack on IPFS?\n\n[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)\n\n## License\n\nipfs-geoip is [MIT](LICENSE) licensed.\n\nThis library includes GeoLite2 data created by MaxMind, available from [maxmind.com](http://www.maxmind.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-shipyard%2Fipfs-geoip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs-shipyard%2Fipfs-geoip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-shipyard%2Fipfs-geoip/lists"}