1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120# 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<CountryResponse>(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).**