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

$3

``js
npm install --save ipfs-geoip
`

$3

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

`html

`

The response in the console should look similar to:
`js
{
"country_name": "USA",
"country_code": "US",
"region_code": "VA",
"city": "Ashburn",
"postal_code": "20149",
"latitude": 39.0469,
"longitude": -77.4903,
"planet": "Earth"
}
`

Usage

$3

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:

`js
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)
}
`

$3

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:

`js
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

$3

Returns a promise that resolves to an object of the form

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

$3

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

Maintenance

$3

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.

$3

There is a generator included, that can be run with

`bash
$ 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:

`console
$ 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:

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

$3


License

ipfs-geoip is MIT licensed.

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