ipfs-geoip

IPFS GeoIP

GeoIP lookup over IPFS

Table of Contents

• IPFS GeoIP
• Table of Contents
  • Install
    • NPM
    • CDN
  • Usage
  • API
    • lookup(ipfs, ip)
    • lookupPretty(ipfs, multiaddrs)
  • Maintenance
    • CIDs of the lookup dataset
    • Updating GeoLite2 dataset
  • Testing in CLI
  • Contribute
    • Want to hack on IPFS?
  • License

Install

NPM

npm install --save ipfs-geoip

CDN

Instead of a local installation (and browserification) you may request a specific version N.N.N as a remote copy from jsDelivr:

<script type="module">
  import { lookup } from 'https://cdn.jsdelivr.net/npm/ipfs-geoip@N.N.N/dist/index.min.js';
  const gateway = 'https://ipfs.io'
  console.log(await lookup(gateway, '66.6.44.4'))
</script>

The response in the console should look similar to:

{
    "country_name": "USA",
    "country_code": "US",
    "region_code": "VA",
    "city": "Ashburn",
    "postal_code": "20149",
    "latitude": 39.0469,
    "longitude": -77.4903,
    "planet": "Earth"
}

Usage

With public gateways (default)

If gateways is a string or array of strings with public gateway URLs, it will be used for fetching IPFS blocks as application/vnd.ipld.raw and parsing them as DAG-CBOR locally via @ipld/dag-cbor:

const geoip = require('ipfs-geoip')
const exampleIp = '66.6.44.4'

const gateways = ['https://ipfs.io', 'https://dweb.link']

try {
  const result = await geoip.lookup(gateways, exampleIp)
  console.log('Result: ', result)
} catch (err) {
  console.log('Error: ' + err)
}

try {
  const result = await geoip.lookupPretty(gateways, '/ip4/' + exampleIp)
  console.log('Pretty result: %s', result.formatted)
} catch (err) {
  console.log('Error: ' + err)
}

With custom block getter function

It is also possible to use it with local or remote IPFS node by passing block getter function, e.g., one that exposes ipfs.block.get Core JS API:

const geoip = require('ipfs-geoip')
const exampleIp = '66.6.44.4'

const ipfs = require('ipfs-http-client')()

try {
  const getBlock = (cid) => ipfs.block.get(cid)
  const result = await geoip.lookup(getBlock, exampleIp)
  console.log('Result: ', result)
} catch (err) {
  console.log('Error: ' + err)
}

API

lookup(ipfs, ip)

Returns a promise that resolves to an object of the form

{
  "country_code": "US",
  "country_name": "USA",
  "region_code": "CA",
  "city": "Mountain View",
  "postal_code": "94040",
  "latitude": 37.3860,
  "longitude": -122.0838,
  "planet": "Earth"
}

lookupPretty(ipfs, multiaddrs)

Provides the same results as lookup with the addition of a formatted property that looks like this: Mountain View, CA, United States, Earth.

Maintenance

CIDs of the lookup dataset

The current root hash for lookups is defined under GEOIP_ROOT in src/lookup.js.

It is a proprietary b-tree generated from source files provided defined under DATA_HASH in src/generate/index.js.

Updating GeoLite2 dataset

There is a generator included, that can be run with

$ npm run generate

This 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.

It reads original GeoLite CSV files provided from DATA_HASH directory defined in src/generate/index.js, and turns them into a 32-way branching b-tree of DAG-CBOR objects.

The tree is saved as ipfs-geoip.car and the root CID is printed to the terminal. It should then be imported to IPFS and the root CID should be pinned in multiple locations, and stored as the new GEOIP_ROOT in src/lookup.js

👉 this library uses dag-cbor and reads raw blocks via ipfs.block RPC, but could be refactored to fetch blocks as application/vnd.ipld.raw from a regular HTTP Gateway.

Testing in CLI

It is possible to run tests against a local gateway by passing IPFS_GATEWAY:

$ IPFS_GATEWAY="http://127.0.0.1:8080" npm test

You can find an example of how to use this in example/lookup.js, which you can use like this:

$ export IPFS_GATEWAY="http://127.0.0.1:8080"
$ node example/lookup.js 66.6.44.4
Result: {
  "country_name": "USA",
  "country_code": "US",
  "region_code": "NY",
  "city": "New York",
  "postal_code": "10004",
  "latitude": 40.7126,
  "longitude": -74.0066,
  "planet": "Earth"
}
Pretty result: New York, NY, USA, Earth

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

ipfs-geoip is MIT licensed.

This library includes GeoLite2 data created by MaxMind, available from maxmind.com.

Changelog

9.2.0 (2025-02-19)

Features

• updated dataset (GeoLite2-City-CSV_20250218) (#116) (1da78de)