Awesome
IPFS GeoIP
GeoIP lookup over IPFS
Table of Contents
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 viaipfs.block
RPC, but could be refactored to fetch blocks asapplication/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.