Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/GitSquared/node-geolite2-redist
Redistribution of MaxMind GeoLite2 GeoIP databases as an npm library
https://github.com/GitSquared/node-geolite2-redist
geoip maxmind nodejs npm-package
Last synced: 3 months ago
JSON representation
Redistribution of MaxMind GeoLite2 GeoIP databases as an npm library
- Host: GitHub
- URL: https://github.com/GitSquared/node-geolite2-redist
- Owner: GitSquared
- License: other
- Created: 2020-01-21T08:17:46.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-22T00:26:13.000Z (3 months ago)
- Last Synced: 2024-08-22T02:01:11.787Z (3 months ago)
- Topics: geoip, maxmind, nodejs, npm-package
- Language: TypeScript
- Homepage: https://gitsquared.github.io/node-geolite2-redist/
- Size: 32 MB
- Stars: 78
- Watchers: 8
- Forks: 15
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# node-geolite2-redist
[](https://github.com/GitSquared/node-geolite2-redist/actions?query=workflow%3A%22Databases+Updater%22) [](https://www.npmjs.com/package/geolite2-redist) [](https://nodejs.org/en/about/releases/) [](#typescript)
---
MaxMind's GeoLite2 free databases as an npm library. **As this is a redistribution, you don't need a MaxMind license key.** However, some additional legal restrictions apply, make sure to read this README and the [Legal Warning](#legal-warning) carefully before deciding to use this.
You will need a database reader capable of reading `.mmdb` files, like [node-maxmind](https://www.npmjs.com/package/maxmind), if you wish to use the data.
This package is compatible with the 3 GeoLite2 databases, namely:
- `GeoLite2-ASN`
- `GeoLite2-Country`
- `GeoLite2-City`
For more info check out the [MaxMind website](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).
Due to license requirements, **this package automatically updates the databases in the background** when it detects that a new version is available. This should be transparent for most usecases, if you're experiencing any problem with it, please file an issue.
See [Legal Warning](#legal-warning) section for more info on licensing and limitations.
## Usage
### Installing
`npm install geolite2-redist`
### Using the geoip data
Example geoip lookup in a Node environment, using the `GeoLite2-City` database with `node-maxmind` as a db reader:
#### Javascript
```javascript
const maxmind = require('maxmind');
// This module is distributed as en ESM module (import...from... syntax), but you can
// use an import() promise to make it work without switching to ESM!
import('geolite2-redist').then((geolite2) => {
return geolite2.open(
'GeoLite2-City', // database name
(dbPath) => maxmind.open(dbPath) // function that builds a useful db reader
)
}).then((reader) => {
const lookup = reader.get('185.194.81.29')
console.log(lookup.country.iso_code) // FR 🥖🇫🇷
// Calling close() here shuts everything down nicely and clears up Node's event loop.
reader.close()
})
```
#### Typescript
```typescript
import geolite2, { GeoIpDbName } from 'geolite2-redist';
import maxmind, { CountryResponse } from 'maxmind';
(async () => {
const reader = await geolite2.open(
GeoIpDbName.Country, // Use the enum instead of a string!
(path) => maxmind.open(path)
)
const lookup = reader.get('185.194.81.29')
console.log(lookup.country.iso_code) // FR 🥖🇫🇷
reader.close()
})();
```
### Preloading databases
You can add this to your `package.json` to preload the databases after running `npm install`, instead of downloading them the first time `open` is called:
```json
{
"scripts": {
"preload": "node -e \"import('geolite2-redist').then(geolite => geolite.downloadDbs())\""
}
}
```
## API
You can find a more detailed documentation [on the Typedoc-generated website](https://gitsquared.github.io/node-geolite2-redist/modules.html).
## Legal Warning
Privacy regulations (CCPA in California, GDPR in Europe) that implement the right-to-forget have affected MaxMind's EULA & licenses.
In a nutshell, you should always make sure your GeoIP databases are up to date, which this library conveniently does for you ;)
That said, please carefully read the LICENSE and EULA files. The databases are provided under certain restrictions and obligations, most notably:
- You cannot prevent the library from updating the databases.
- You cannot use the GeoLite2 data:
- for [FCRA](https://www.ftc.gov/enforcement/statutes/fair-credit-reporting-act) purposes in the USA,
- to identify specific households or individuals, worldwide.
If you plan on using `node-geolite2` behind a firewall, you need to whitelist the [GitHub IP range](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses) so that the package can reach the databases mirror.
## Compatibility
We follow the OpenJS Foundation's [deprecation schedule](https://nodejs.org/en/about/releases/) and support all maintained Node versions.
## Alternatives
If you do have a MaxMind license key (which you can get by signing up [here](https://www.maxmind.com/en/geolite2/signup)), you might prefer using [`node-geolite2`](https://github.com/runk/node-geolite2), which this repository is originally a fork of.
## License
The databases themselves are provided by MaxMind under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
For the library, see [LICENSE](https://github.com/GitSquared/node-geolite2-redist/blob/master/LICENSE).
---
**This software package includes GeoLite2 data created by MaxMind, available from [https://www.maxmind.com](https://www.maxmind.com).**