whizzzkid / ipfs-geoip

geoip lookup over ipfs

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 remote copy from jsDelivr:

<!-- loading the minified version using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/ipfs-geoip@8.0.0/dist/index.min.js"></script>

When using prebuilt bundle from CDN, ipfs-geoip will be exposed under window.IpfsGeoip

Usage

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

const exampleIp = '66.6.44.4'

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

try {
  const result = await geoip.lookupPretty(ipfs, '/ip4/' + exampleIp)
  console.log('Pretty result: %s', result.formatted)
} 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, which is stored as ipfs json objects.

The produced CID should then be pinned and stored as the new GEOIP_ROOT in src/lookup.js

👉 Note: this library uses old type of ipfs json objects for legacy reasons, be mindful of that and do not use its code as an example. Modern code should use dag-cbor and ipfs.dag or ipfs.block APIs.

Testing in CLI

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

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